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Introduction 



ITic V-Systcm is a mcssagc-bascd distributed operating system designed primarily for liigh-pcrformancc 
woricstations connected by local networks. It permits the workstation to be treated as multi- function 
component of the distributed system, rather than solely iis a intelligent terminal or personal computer. 
Ultimately, it is intended to provide a general- purpose program execution environment similar to some 
degree to Unix. The programs are intended to interact with each other, and witli programs running on 
traditional timesharing systems, to produce an integrated distributed system. 



1.1. The User Model 

One of tlie most important functions for the workstation is to provide st^^tc-of-thc-art user interface support. 
In particular, the workstatit)n should function as a from end to all available resources, whether local to tlic 
worksuuion or remote. To do so, the V-System adheres to Uirce lundamentiU principles: 

1. The interface to application programs is (reasonably) independent of particular physical devices or 
intervening networks. 

2. 'I'hc user is allowed to perform multiple tasks simultaneously. 

3. Response to user interaction is fast. 

In addition, facilities arc being developed to permit a consistent interaction discipline across applications. 

When tlie user boots his workstation he may commutiicate with one of two entities: an e.xeculivc or the view 
manager. The user executes commands (application programs) from within an executive, which is the 
equivalent of a Unix shell or Tops-20 Kxi<c. The applications may run local to ilic workstation or remote. 
'ITiey may be written with tlie particular worksuuion in mind, or mn in "terminal emulation" mode. They 
may require I/O modalities other tlian traditional text, namely, graphics. 

l^iich application may be associated with one or more separate, device-independent virtual graphiea 
terminals {SG'V). A VGT may be created by the user (via tlie view manager) or by tlie activity itself, luich 
VGT may be used to emulate cither a page-mode VT-100 terminal or a 2-dimensional raster graphics 
terminal. 

When tl)e user wishes to initiate a new application concurrent with existing applications, he must first create 
a new VGT, with an associated executive. To do so, the user communicates with die view manager. The 
executive serves as a command interpreter from whicli the desired activity may be initiated. The user can 
create a new executive, with VGT, at any lime, asynchronous to any existing activities. When a particular 
activity requires additional virtual terminals, it is free to create them. These VGTs will be deallocated when 
the activity terminates, whereas VGTs created by tlie user may only be deallocated by the user. 

Virtual terminals are mapped to the screen when and where die user desires. Each such mapping is temied 
a view. When an activity creates a new VGT, it prompts die user to specify the default view. Thereafter, the 
user may create as many additional views as he wishes. To some extent, he may manipulate views of die same 
VGT independent of all other views of diat VGT, for example, pan or zoom. All VGT management is 
performed via die view manager. 
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INTRODUCTION 



1 .2. The System Model 

'Flic V-Systcm adheres to the sener model'. The world consists of a collccdon of resources accessible by 
clients^ and managed by servers. A server defines die abstract representation of its rcsource(s) and die 
operations on diis representation. A resource may only be accessed or manipulated througli its server. 
Because servers arc constructed with well-defined interfaces, the implementation details of a resource arc of 
concern only lo its server. Note diat a server frequently acts as a client when it accesses resources managed by 
other servers. Thus, client and 5^rv<?r are merely roles played by a process or module. 

Clients and servers may be distributed throughout die (intcr)network. By default, access to resources is 
network transparent; a client may access a remote resource with die same semantics as it accesses a local 
resource. 'Hie result is an environment in which clients may communicate with servers without regard for die 
topology of die distributed system as a whole. However, we do not intend diat a client cannot determine or 
influence tlic location of a particular resource, raUier diat a transparent mechanism is available. Moreover, we 
allow for clients and servers diat were not written with network- transparent access in mind. 

Logically, dien, die V-Systcm consists of a distributed kernel and a distributed set of server processes. A 
standard program environment is defined, die principal instance of which is the C program library, 'llic C 
library includes rinuimc support for standard C and (jNix-likc library functions to facilit«iie the porting of 
existing C programs. 

1 .2.1 . The Distributed Kernel 

'ITic distributed kernel pnovides network-transparent interprocess communication based on synchronous 
message- passing. It consists of the collection of kernels resident on die participating machines. The host 
kernels may be implemented at a base level (as on die Sun workstation) or a guest level (as under Vax/Un[x). 
The host kernels are integrated via a low-overhead inter'kernel protocol diat supports transparent interprocess 
communication between machines. 

1.2.2. Servers 

Servers include: 

virtual graphics terminal server 

Provides all terminal management functions. One per workstation. 

Internet server I'rovidcs Arpa Internet llVrCP support 

pipe server Provides asynchronous, buffered communication facilities similar to U Nix pipes. 

learn server Provides team creation, destruction, and management One per workstation. 

exception server Fields process exceptions and dispatches dicm to registered handlens, such as debuggers. 
One per workstation. 

storage server Provides disk storage. 

device scrver(s) Interfaces to a specific physical device, such as the console, mouse, serial line, or disk. 

local name server Provides locally defined character string names for (possibly) remote resources. One per 
workstation. 



A client is a program requesting access to a resource typically on behalf of a human user. 



V-SYSTl'M 5.0 UIM-liRI-NCl- MANUAL 



nil- APPLICATION MODEL 



3 



1.3. The Application Model 

Using tlic kernel well requires understanding the model of processes and messages that the kernel provides, 
and how they are intended to be used. Processes represent logical activities within the application. I'hcy are 
intended to be sufficiently inexpensive to allow the use of multiple processes to achieve the desired level of 
concurrency. In particular, multiple processes may share the same address space or learn, to facilitate fmc- 
grain sharing of code and data. A team must be entirely contained on a single machine. 

Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique 
process identifier that is used subsequently to specify that process. 

Synchronous message-passing facilitates communication between processes that looks to the sender like a 
procedure call. That is, the sender blocks until a reply to his request is received. Greater flexibility is 
provided to die receiver to allow scheduling of requests. Messages arc addressed to the process identifier of 
the recipient; there is no concept of a mailbox or port distinct from a pr(x:ess. 

Messages are short and fixed-length. To fiicilitate transfer of large amounts of data, a separate data transfer 
facility is provided. Specifically, a process can pjiss, in a message, access to an area in its team space. This 
facility ft)ll()ws the procedure paradigm in being used primarily to access what arc logically "call-by- 
refercnce" parameters. Synchronization between tlic two processes involved in the data transfer is guaranteed 
by virtue of tlic fact tliat the recipient will not reply to die sender (and hence awaken him) until the transfer is 
complete. 

'fhc kernel implements a low-level naming service diat provides efficient access to server processes. A 
process can register its process identifier as corresponding to a particular logical process identifier. Clients can 
subsequently query die kernel as to Uic process identifier corresponding to a specific logical prtxress identifier. 

Process scheduling is stricdy priority-based. The effective priority of a process is the sum of its process 
priority, which is defined and fixed when the process is created, and its team priority. Team pi ioritics can be 
dynamically varied by a server process to provide time-sliced aheduling. 

1.4. Outline 

'^Hic remainder of this manual consists of five parts: 



Part I Coiniiiiaiid.s: describes die user interfiicc and available appiiaition programs. 

Part 2 Program Knvironnicnt: defines the V-System program environment in terms of die 

existing C program library. 

Part 3 Servers: defines die sttindard I/O prot(x:ol and presents die server interfaces. 

Part 4 Kernel: describes the distributed kernel. 

Parts Appendices 



Any part of the V-System may change without notice. Therefore, this documentation should be regarded as 
advisory. 
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Part I: 
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— 2 — 

Using the V Executive 



2.1 . Introduction 

The V executive is the part of the V system that accepts user commands from tlie keyboard and causes them 
to be executed. It corresponds to the Unix shell or 'l^ops-20 Exec, There are currently several versions of tlie 
executive, including two called exec and vgtscxec} The two versions dilTcr only in tlicir handling of terminal 
I/O. The exec program mns a single executive, which uses the kernel console device, while the vgtsexcc uses 
the Sun Virtual Graphics Terminal Service to provide any number of simultaneous execs. Although initially 
the vgtsexcc provides one executive, the user can create and delete executives using the Exec 
Control command of ti\Q view manager, described in the next chapter. 

'Vhc basic operation of the executive is to read command lines and execute commands. The first field on a 
command line is tlie command name; the rest are arguments to be passed to the command. Fields are 
separated by spaces. A command name can be a built-in exec command, tlie name of a file containing a 
program compiled to run under the V system, or tlie name of a program to be run on a server, such as Unix. 
The executive provides a simple search path mechanism for commands. It looks first for a V program in die 
current context (i.e., directory), next in the current [bin] context, and finally in die [public] context. If it still 
cannot find it, it will try to execute the command remotely, on the server that is providing your current 
context 

'ITie executive waits for each command to exit, unless the last field on the command line is tlic single 
character &. In this case, the command ams in the background, while tlie executive continues to accept 
commands from tlie keyboard, in the vgtsexcc, Uiere is a view manager option to terminate a program 
nmning in the foreground, but the plain exec currently provides no way to do this. A program running in the 
background may be terminated using tlie clesiwy commund (see chapter 4). 

Other exec features are described in section 2.7. 



2.2. Running the V Executive 

When you come up to an idle Sun workstJJtion, it may be in one of several states. If die screen is blank, it is 
probably running V, but idle. The VGTS blanks Llie screen on idle worksuitions after a lew minutes of 
inactivity. Move the mouse slightly or press any key on die keyboard to restore die display. A previous user 
may have lell one or more of his sessions (see below) active. The command 

logout 

will tcnninatc Uiem ail and get you off to a fresh start. 

If tlic workstation is rmmlng some other program, dead, powered down, or die like, it will be necessary to 
reboot it, as described in the following paragraphs. 

There are several brands of Sun workstation in existence, and booting procedures vary depending on die 
brand. The two major kinds arc those made by Cadlinc, which are black, and those made by Sun 
Microsystems (SMI), v/hich are white. Many other computers based on the same 68000 CPU board may also 
run the V system, but deuiiis may be different 



%cc section SliRVERUXEC for a description of the serverexec, which is used only on dedicated server machines. 
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A Cadlinc workstation in a random slate can be reset to tlie prom monitor by typing 
<crRL><Siin'D<BRi-AK>, pfcssing die reset button, or (in desperation) power-cycling die wori(station. It is best 
to try pressing die comma key on a Cadlinc's numeric keypad before resetting it. If the V kernel is active at 
diat point, this key instructs it to turn off die mouse, necessary for proper opcraUon of die prom monitor. 
Otherwise, you may have to power cycle die workstation or keyboard to regain control. 

On the SMI workstation, hold down ERASn r-oi' (White Keyboard) or Sirr-UP (Black keyboard) and hit die 
"A" key. Tlicrc is no reset button on SMI workstations, and die SMI mouse does not need to be shut off. 

Suns diat have an ordinary terminal as their console can usually be brought into die prom monitor by 
hitting die tcrminars BREAK key. Sometimes dicrc is a reset button or switch attached. 

It is always necessary to reset die workstation by pressing tiie reset button or using die Sun monitor's kl 
command before running tlie V kernel. On SMI Suns, die kl command destroys die type font used by die 
PROM monitor to draw characters on die display, taut diis is restored by the. next b command. You can also 
use Ic2 on SMI Suns, which repeats die powcr-on diagnosdcs and dius takes much longer dian kl, but docs 
not destroy die font 

To run the V executive on a Sun worksttition, reset die workstation and type the command 
n V 

to Llie Sun monitor. (Use b instead of n on SMI Suns.) If your Sun has a frame buffer, diis command loads 
die vgtsexec, or a small version of die vgtsexec if you have 256 Kbytes of memory or less. If you have no 
frame buffer, llic n V command loads die plain exec. You can force die plain exec to be loaded by typing 

n VV 
to die monitor. 

Both V and VV arc special vcreions of die Vload program, "hardwired" to load a particular command. See 
chapter 12. 

2.3. Contexts and the Local Name Server 

A context in the V system is a generalization of die directories provided by other systems such as Unix. 
Hach pnKCSS (and d>us each cxccudve) has its own current corucxt. A lllenumc is normally interpreted in the 
current context, unless it begins with a square bracket (*['). Any lllenamc diat begins with a square bracket is 
sent to the l(K-al name server, which inlerpreui the part of die name in brackets, dien forwards die request olT 
to die specified context Kw example, 

[diab1o]/usr/f iles 
means die name /us r /files is to be interpreted in tlie context named [diablo]. 

Tlie local name server predefines several context names, and others are defined by tlie login program and 
die executive. Users can define dicir own local names using the define and undejine commands. The 
command 

listdir [context] 
lists die local context names currently defined. 

2.3.1 . Changing the Current Context 

The cd (change directory) command can be used to change die current context for an exec. The command 
format is 

cd pathname 
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ITic pathniunc is interpreted in tlic (previous) current context. If tlic pathname is omitted, [liomc] is assumed 
(sec section 2.4.1). When an exec is created, its current context is set to die current value of [home]. 

2.3.2. Getting Context Names 

The cotUext or pw^/ command will print a name for a context. It tries to find die most informative of die 
possible ways of naming die context. The command format is 

context pathname 

If die padinamc is omitted, the command prints a name for die current context This is the most common 
use. 

2.3.3. Defining and Undefining Names 
"Ilic command 

define namei name!... nameN oldnanie 

or 

define name! mme2 ... nameN -1p lo^icalpid 

defines U)cal names [name I] Uirough [nameN] to refer to the s<imc context as the current value of t)ldname or, 
if the "-Ip" opdon is used,, to refer to die context corresponding to the supplied logical pid. (System logical 
pids are defined in <Vcnviron.h>.) Brackets are optional on namcl through namcN, while oldnamc is 
interpreted in die current context unless surrounded by brackets. Any previous meanings for namcl through 
namcN arc lost. 

The command 

u n de fine namel name2 ... nameN 
removes any existing local definitions of [namel] Uirough [nameN], Brackets arc optional on diese names. 



2.4. Sessions 

The V system uses die concept of a scission to provide a relatively sccine fomi of Hie access over a local 
network. To gain access to files on a host machine, it is ncccssiiry to create a session on that machine, by 
providing a valid user name and password to a server pr{K:ess running on Uic host. The session created has 
diat user's file access permissions, so die existence of a V server on a machine does not add any additional 
complications to security or create any new security holes. Both the server pnKcss and die sessit)n it creates 
appear as ordinary V processes which can send and receive messages using the distributed V kernel 
interprocess communication protocol. 

2.4.1. Login 

I1ic login command is used to create sessions. The command format is 

login hostname sessionnaine 

where both die host name and session name are optional. If the host name is omitted, die login program will 
prompt for it. if die session name is omitted, it defaults to be the vSame as die host name. 

'llic login program always prompts for a user name and password. Tlic password is not echoed when typed. 
An error message will be printed if die session cannot be created, or die user had an Incorrect name or 
password. 

Tlic login program registers die user's home directory on die newly created session widi the local name 
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server. Thus after a 

login diablo 
command, die name 

[d1ab1o]papers/nam1ng.inss 
refers to the Tile papers/nami ng .mss under the user's home directory on tiic host named diablo. 

Tlic login program defines the local name [home] as an alias for tlic user's home directory on the last session 
created, and tiie local name [bin] as an alias for the V public directory on die host providing that session, if it 
maintains one. 

After die login command is nm, the exec automatically changes its current context to die new value of 
[home]. Remember diat diis docs not change die current context for any other process, including any of die 
other execs diat may be running on die workstation. 

2.4.2. Logout 

'Hie logout command is used to terminate sessions. The command format is 
logout sessionncune ... 

where die session names are optional. If one or, more names arc given, each of the named sessions is 
terminated. If no names arc given, ail sessions known to die local name server are terminated. After it 
fmishes, die logout command prints a count of die number of sessions logged out. If a session name was 
given and no such session was found, an error message is printed. 

Logging out a session can cause the current contexts of one or more processes on the workstation, the name 
[home], and/or die name [bin] to become invalid. Hxccutivcs ti7 to recover from diis situation, but other 
programs may not be able Co. IDo not log out a session if some program on your workstation is still using it 

2.4.3. Accessing Files Without a Session 

For convenience, the V servers provide a wiiy of accessing a ccrtiiin limited set of files without first creating 
a sessit)n. Any of the programs kept in die stiindard V public directory may be run without creating a session. 
The name [public} is predefined by thclocal name server to refer to this service. 

On a workstiUion with no sessions in existence, the names [home] and [bin| arc normally both defined to 
equal [public]. The current directory of die first exec created when V is booted is also set to [public]. 

Tlie name [public] has die special property that it is mapped to a logical process id (and well-known context 
id) instead of a specific server process. lt*ich dme the name is used, it is automatically mapped to a currently 
existing server, die one which responds first to die name server's GetPid request. Other names which are 
defined to equal [public], as mendoncd above, get its current value when dicy arc defined; diey do not cause a 
GciPid on each use. 



2.5. Remote Program Execution on a Session Server 

If the executive fails to find an appropriate load file for a command, it will attempt to execute the command 
on die server providing its current context by invoking die fexccufe program. Thus, for example, when a V 
server on Unix is providing die current context, ail die standard Unix commands like finger, make, or Is are 
available. The output of die Unix command is printed on die standard output file. 

You can also supply input to remote commands. The character echoing and line editing. on this input arc 
done on die workstiition, not by die session server machine. You can type 

control-t c [return] 
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to send an end of file to tlie remote command, or 
control-t e [return] 

to cause die remote command to exit Type control -t twice to send a single control "t- character to die 
remote command. 

Since both the input and output arc done through pipes, and input is a line at a lime, many Unix programs 
which expect to be run on tty devices (such as emacs, telnet, more, etc.) do not worlc in tliis mode. Such 
programs can only be ran by logging in to the Unix machine, perhaps using one of die V telnet programs to 
connect to it (sec chapter 4). 

The V servers do not provide execution of Unix commands without a session. If the executive tries to 
execute a Unix command in the [public] context, Uic V server returns an "Illegal request" error. 



2.6. Remote Execution on a Designated V Host 

A command can also be executed remotely by cxplicidy designating another host. This is done by 
specifying tlic process id of the team server for the ht)st on which the command is to be run. (Syntax details 
arc described in 2.7.6.) Remote execution of this type is transparent to die user in duit 1/0 is still directed U) 
the local host. 



2.7. Executive Facilities for Command Specification and Modification 

The executive provides various facilities for specifying and editing command lines and lor redefining 
various aspects of command execution. 'Vhc syntax and semantics of each is described below. 

2.7,1 . Line Editing F-acilities 

Command linos can be edited with Rmacs-stylc line-editing keys. More specifically, the following editing 
commands are available. Cl'RI.-x means striking Uie Control key and the x key simultaneously; BSC-x 
means striking the llscapc key and then tJic x key. 



CFRL-a Move cursor to beginning of the command line. 

CFRI .-b Move cursor back one character. 

CrR[--c Kills die Break Process, usually die command running in the current executive. 

CI'RL-d Delete character under the cursor. 

Cl'RL-c Move cursor to die end of die command line. 

CTRL-f Move cursor forward one character. 

CI'RL-g Abort Uic command. The line editor will pass the command line, followed by a Cl'RL-g, to 
die client program, which is responsible for delecting die Cl'Rl--g and reacting to it. 

Cl'RL-h Delete die character before die curstir. Kquivalcnt to die Di'L key. 

CTRL-k Delete die command line from die cursor to die end of die line. 

CI'RL-t Transpose die two characters preceding die cursor. 

CI'RL-u Delete die command line up to the cursor, 

Cl'RL-w Delete from die cursor to the beginning of die current word. 
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CTRL-z Causes an Fud of File indication to be sent to the application reading the line. This will 
terminate the Hxecutive if no application is running. 

ESC-b Move cursor to the beginning of the current word. 

ESC-d Delete from the cursor to the end of the current word. 

ESC-f Move cursor past the end of tlie current word. 

ESC-h Delete from the cursor to the beginning of tlie current word. Same as CIUL-w. 



Printing characters are normally inserted at the cursor. Commands are submitted to tiie executive for 
execution by hitting carriage return. I'his can be done regardless of where in tlic command line ttie cursor is. 

2.7.2. Command History References 

The executive also maintains a history of tlie last 20 command lines that the user has typed in. These 
command lines may be referenced by typing tiie character I immediately followed by a prefix of the desired 
command line. Thus if the command line 

cp /ng/ng/V/cmds/exec/exec . c /tmp/exec.c 

was typed in, then it can be referenced by typing (for example) 

Icp 

If a non-unique prefix is specified then the most recent command with tliat prefix is talccn. Another special 
form of reference is 1 1 , which references the previous command line. 

When a command line is referenced it is redisplayed for further line editing and verification. 1lius in the 
previous example typing 

Icp 

will cause the executive to display 

cp /ng/ng/V/cinds/exec/exec . c /usr/sun/Vboot/exec . c 

with tlie cursor sitting at the end of the line. The user can then hit carriage return to reexecute the line or can 
edit it first to derive a new command. 

The command history will cause die executive to list Uie command lines it has stored in its history record. 
The most recently executed command will be at tlie bottom of the list 

2.7.3. Command Aliases 

Command names can be alhiscd by means of the alias command. ITius. for example, typing 
alias e ved 

will cause tlie command name "c" to be replaced by "ved" in subsequent command lines. Note that aliasing 
is done ott/y for command names and not for command argumcnLs. (Remember tliat Uie conimanU name is 
tlie first word of a command line.) 

Aliases specify a string for replacement of the alias word. Huis one can create aliases such as 

alias test /ng/mmt/tsst/tastcopy -d 
'I1icn typing something like 

test filel flleZ 
will cause the command 

/ng/mrat/test/t8Stcopy -d filel flleZ 
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to be submitted to the executive (bi- execution. 

A list of all defined aliases can be obtained by typing alias without any arguments. Tlie command unalias is 
used to remove an alias dcfmition. Specifying a new alias definition Ibr a command name simply replaces the 
old one. 

2.7.4. I/O Redirection and Pipes 

I/O redirection and specification of pipes between two (or more) commands is done using the same syntax 
as is used by the Unix shells. I'hus input can be redirected to come from a file by specifying 

cmd < file 

and output can be redirected to a file by specifying 

cmd > file 

or 

cmd » file 

The latter form specifics tliat the output should be appended to the file whereas tlie first form will overwrite 
any data already existent in the file. Krror output can be redirected by specifying >? or >>?. The forms >& 
and »& redirect bodi standard output and standard error to the same file. 

A special fonn of redirection is available for bidirectional files, such as tlic serial lines available on Suns. 
Specifying 

cmd <> file 

causes die command's input and output to be redirected to the same file. To be precise, the file is opened in 
FCRF*!ATE m.<xle, and standard output is redirected to the instiince Uuis created. Standard input is redirected 
to come from an instance whose id is equal to the output instance id plus I. This matches a convention used 
by several V-System 1/0 servers. The form <>& also redirects standard error to die siime instance as standard 
output. 

Pipes can be set up between several commands by separating diem with a | on die command line. Thus, 
for example, die command line 

cmdl I cmd2 1 cmd3 •> log 

will create two pipes and redirect 1/0 so that tlie output of cmdl will be used as tlie input to cmd2, the output 
of cmd2 will be used as Uic input to cmd2, and the output of cmd2 will be redirected into Uic file log. 

All the special characters described above must be surrounded by spaces for die executive to recognize 
Uiem. Redirection clauses must appear after ail arguments to be passed to Uic command. 

2.7.5. Concurrent Commands 

Commands can be specified as being concurrent by including an & at tlic end of the command line. This 
e;uises die executive to return inuncdialely to the user Ibr another command ratlier tlian waiting until the 
current command completes. Also, while nonconcurrent (foreground) commands are terminated if their 
executive is deleted, concurrent (background) commands will continue even if die executive Uiat initiated 
Uicm goes away. 

'I1ic & must be preceded by a space for the executive to recognize iL 
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2.7.6. Execution of Commands on Another Host 

Commands can be designated to execute on another host by including 
9 TeamSspvepPId 

at the end of the command line. (Note: an & can be specified in addition to this.) Here TcamScrverPid is the 
hexadecimal process id of the team server residing on tlic remote host where the command is to be executed.^ 

Remote execution is transparent to the user in that the I/O of tlie command is still directed to the local host 
and will be displayed in the same manner as if the command were executing locally. 

The 9 sign must be surrounded by spaces for tlie executive to recognize it. The remote execution clause, if 
present, must follow all arguments to the command (but may be intermixed freely with redirection clauses). 



Using ihc hex piU Ls a icmporary measure until some Tonn of host name service Ls available. 
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— 3 — 

The View Manager 



The view manager provides an intcrftice between the user and tlie VGTS. The programmer's interface to 
the VGTS is described in the V-System Programming Environment Manual and tlie internal structure of tlic 
VGTS is described in tlic V-Sysiem Servers Manual. 'Hie program creates SDKs and objects within them, and 
associates tliesc objects with Virtual GraphicsTerminals (VGTs). Ilirough the view manager, the user maps 
these VGTs onto physical screens, and manipulates the resulting views. Tlic VGTS multiplexes both the 
output devices (the screen) and the input devices (keyboard and mouse) among all the programs that use 
them. The VGTS is no longer physically integrated with the executive, although the view manager does 
provide an interface to tlic exec server. The line-editing functions described in section 2.7.1 are provided by 
the VGTS, like any terminal agent. 



3.1 . VGTS Conventions 

Virtual terminals appear .as white overlapping rectangles on the screen, with a black border and a label near 
the top edge. 'Hierc is at most one virtual terminal (usually a pad, or text-only virtual tenTiinal) that is getting 
input from the keyboard, along with possibly other virtual terminals getting input from tlie mouse. 'ITiis is 
indicated by a flashing black box for a cursor in the text virtual terminal, and a black label on all the views 
that arc accepting mouse input Note that all virtual terminals are always active in the sense tliat any 
application may run or change the display in any virtual terminal at any time independent of tliis selection; it 
only applies to input. 

Clicking the left or middle button of tlie mouse in a non-selected virtual terminal will cause it to be selected 
for input Views of selected pads will be brought to tlic top. The input pad can be changed by using control 
up-arrow (octal 036) followed by a single command character. The only command characters interpreted by 
tlic VGTS arc 1-9 to select the given pad for input 

'ITicrc arc a few conventions for using tlic mouse with the VGTS. A "Click" consists of pressing any 
number of buttons down and releasing them at a certain point on the screen. While Uie buttons are down 
tliere may be st>mc kind of feedback, like an object which follows tlic cursor. The click is usually only acted 
upon when ail tlic buttons arc released, so if you decide you have made a mistake after pressing the buttons 
you can slide tlie mouse to some harmless position before relc;ising die buttons. Molding all three buttons 
down is also interpreted as a universal abort by most programs and tlic view manager. The click event is sent 
to the program ass(x:iatcd with the view in which tlic event occurred (through its VG'O. 

When a V-System program requests tlic creation of a pad, the cursor will change to the word "Pad". At this 
point hold down any button, and an outline of tlic view which will be created will be tracked on tlie screen. 
Position the view where desired, and let go of tlic button. 



3.2. View Manager Menus 

The view manager menus can always be invoked by moving the cursor to the grey background area or any 
virtual terminal not getting input (except in the banner area) and pressing the Right button. The following 
commands are available from tlie view manager menus: 

Create View Creates another view of an existing VGT. Move the cursor to die desired position of any 
one of the four corners for tlic new viewport Hold any button down, and move the cursor 
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to the diagonally opposite corner. An outline of tlie new view will follow the cursor as it 
moves with the button down. Let the button up, and then point at tlie VG'l" that you 
would like to sec with the left or middle buttons, or hit the riglu button and select the VGT 
from the menu. Normally only used with graphics VGTs. 

Delete View Click one view which is removed from the screen. Warning: if you delete the last View of 
a VGT, it does not destroy the VGT or ihe process associated with it. You can still create 
views of the VGT by using tlic right button menu in the Create View command. 

Move Viewport Press any button to select a viewport to move. While the button is being held down, die 
outline of the viewport will move, following die cursor. Lift up the button at the desired 
position. None of the otlier view parameters arc changed. A shortcut to tliis function is 
obtained by pressing the middle button while pointing to the banner of die desired 
viewport. The viewport outline will follow the cursor until the middle button is released. 

Make Top Brings tlic view to the top, potentially obscuring other views. A shortcut to this function is 

obtained by pressing tlie left button while pointing to the banner of the desired viewport 

Make Bottom Brings Brings the view to the bottom, potentially making visible other views. A shortcut to 
this function is obtained by pressing the right button while pointing to the banner of the 
desired viewpoit. 

Hxcc Control Selects a submenu to create another executive, destroy an executive (and tlic teams timning 
in it), kill a program, or control paged output mode. When you arc creating an executive, 
the outline of the new pad will follow the cursor as you hold die button down. Lift die 
button up at Uic desired position, or press all Uirce buttons to abort. A shortcut to die Rxcc 
Control menu is obtained by pressing both the middle and right buttons while the cursor 
points to Uie gray background or the display area of a viewport not requesting mouse 
information. 

Graphics Commands 

Selects another menu of commands that arc usually only applied to graphics views. These 
are described below: 



Center Window Click die position that you want to become Uie center of tlie viewport Does not change 
die position of the viewport on die screen, just die object within die view. Doing this to 
pads is almost always a mistake. 

Move F.dge.s Push any button down next to an edge or corner, move that edge or corner to Uic new 
position, and let Uie button up. The edge outline slnnild follow the cin"sor as long as you 
hold Uic button down. l!)ocs nut move the object being viewed relative to Uic screen. 

Move Rdgcs + Object 

Similar to die previous command, but diis one drags die underlying object around with the 
moved edge or corner, while die previous command keeps it stiitionary with respect to die 
screen. 



Zoom 



Invokes a /oom mode, indicated by a change in the cursor lo die word "Zoom". You can 
get out of this mode in two dilTcrent ways: Mrst clicking the left or middle buttons when 
die cursor is inside a view of a pad returns from die view manager and selects that pad for 
input As a side cTlcct diat view is also brought to die top. Secondly, you can click die 
right mouse button. The cursor should change back to the normal arrow. 

'ITic left and nuddlc buttons in Zoom mode zoom out and in respectively. That is, the left 
button makes the object look smaller, and die middle button makes it look larger. You can 
remember Uiis because die "outer" (left) button zooms out and die "iiuicr" (middle) 
button 7.ooms in. A shortcut to Uiis mode is available by clicking die middle and left 
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buttons at the same time while the cursor points to the gray badiground or the display area 
of a viewport not selected for input. 

Expansion Depth Click to determine the view, then select the new expansion depth from the menu. Symbols 
will not be expanded more than this many levels into the hierarchy, instead they will be 
drawn as outlines with text for tlicir names if there is room. The default expansion depth is 
infmity, so all levels will be normally expanded. 

Redraws all the views on the screen; necessary only during debugging. 

Click once to turn the grid on if it is off, or off it is on in the view you select The grid dots 
are every 16 screen pixels, and always line up with the origin. 

Enables lots of extra printouts, for maintenance use only. This command asks for 
confirmation, to discourage its accidental invocation. It will not turn on debugging unless 
the response begins with tlic letter y. 

A shortcut to the Graphics Commands menu is obtiiined by pressing boUi die left and right buttons while 
the cursor points to the gray background or the display area of a viewport which is not requesting mouse 
in)x)rniation. 



3.3. Paged Output Mode 

When paged output mode is on, tlie terminal agent stops writing to a pad when Uie pad fills up with output, 
Tlie terminal agent then displays tlie message "Type <space> for next page" and waits for the user to issue a 
command which unblocks the pad. 'Hiis section describes the available commands. 

Most commands arc optionally preceded by an integer argument k. Defaults are in brackets. Star(*) 
indicates that the argument becomes the new default. 



<space> Display die next k lines [current page size] 

•/, Z Display the next k lines [current page size]* 

<CR>, <l .F> Display die next k lines [I] 

q, Q 'I'hruw away all output until the next time input is sent to Uic application program, 

s Skip forward A lines [I] 

S Skip forward to the last line 

f Skip forward k pages [I] 

P Skip forward to tlic last page 



<backspacc>, DEI. Erase the last character of the numeric argument 

Repeat the previous command 

If die user types a character which is not a valid command, die character is treated as a normal input 
character, if line editing mode is on, the CrRL-c and Cl'RL-z commands (sec section 2.7.1) have dieir usual 
effect here. 



Redraw 
Toggle Grid 

Debug 
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3.4. Mouse Escape Sequences 

Inside a pad, when connected to some host through a telnet program, the buttons have the following effect: 

Left Button Sends the sequence escape M <xXy> which positions die Emacs cursor at the position of 
the click. 

Middle Button Selects the clicked pad for input, and brings the view selected to the top. 
Right Button View manager menu, described in the previous section. 
Left + Middle Buttons 

Sends the sequence escape M <xXy> null which sets the Emacs mark to the clicked 
position. 

Left + Right Buttons 

Sends the sequence escape M <xXy> tW which deletes in Emacs from the mark to the 
clicked position. 

Middled- Right Buttons 

Sends the sequence escape M OfX>'> tY which inserts tlie kill butter at tlie clicked position 
in Hmacs. 

'ITic above cscnpc sequences arc enabled by turning on Lhc Report EscSeq bit in the cooking mode of tlie 
virtual terminal. See tlie VGTS chapter of die library manual for more details. 



3.5. Mouse Emulation via the Keyboard 

For the benefit of hardware configurations without a working mouse, tJie VGTS can interpret certain 
keyboard escape sequences as mouse input. The VGTS will only intercept Uicse escape sequences if they are 
sent as a rapid buret ol*charactei"s, as is tlie case when tliey are sent by pressing a function key. If die escape 
sequences are typed manually, the VGTS will detect the space between charactere and pass diem dirough in 
die normal fashion. 

'Hie following is a list of die escape sequences used and the function keys with which diey are normally 
associated on an ANSI (Vl'lOO-style) keyboard. 

HSC [ A (ANSI Down Arrow) 

Move Uic mouse cursor down. 

HSC IB (ANSI Up Arrow) 

Move the mouse cursor up. 

ESC [C (ANSI Right Arrow) 

Move the mouse cursor to die right 

ESC I D (ANSI Left Arrow) 

Move die mouse cursor to the Icll:. 

ESC OP (ANSI PFl) 

Toggle die value of die left mouse button. The new value of die left mouse button is 
displayed in die view manager window. 

ESC OQ (ANSI Pr-7) 

Toggle die value of die middle mouse button. The new value of die middle mouse button 
is displayed in the view manager window. 

ESC OR (ANSI PF3) 
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Toggle the value of the right mouse button. Tlic new value of tlic right mouse button is 
displayed in tlie view manager window. 

ESC OS (ANSI PF4) 

Toggle mouse emulation mode. When mouse emulation mode is OFF, all escape 
sequences except for ESC O S (ANSI PF4) will be passed tli rough as normal, allowing the 
associated flmction keys to perform application-defined functions. The new state of mouse 
cmuladon mode is displayed in the view manager window. 

When the VGTS receives input from a "real" mouse, mouse emulation is permanently disabled. If your 
mouse fails, you must use the "newterm" command to create a new VGTS in order to use mouse emulation. 



v-SYsrnM 5.0 ri-i-I'RI'.nct. manual 



COMMANDS 



20 COMMAND SUMMARY 



V-SYSTHM 5.0 RI'M-UI-NCI* MANUAF. 



COMMANDS 



COMMAND SUMMARY 



21 



_4_ 

Command Summary 



4.1. Workstation Commands 

The following briefly summarizes the currently available commands for V. 



amaze 
biopsy 



bits 
boisc 



cd 

checkers 
clear 



A multi-person distributed game. Docs not (yet) run under the vgts. See chapter 10. 

Prims information about all the processes on the workstation, sorted by team. Several 
options are recognized. The -I option also includes the filename from which each team was 
loaded. (This generally makes the output longer than one screenful.) The -t option 
followed by a pid or the sujpx of a team's filename will cause information to be printed 
only about the team asswiatcd with the pid or filename. More than one pid or nicname 
can be specified - information for each will be printed. To obtain detailed information 
about one or more processes, invoke biopsy with just the pid(s) of the relevant process(cs). 

A program for manipulating bitmaps and fonts. See chapter 9, and the online holp file. 

Prints files on the Boise laser printer. 

Several switches are allowed, preceding the filenames: 

-r Print rotated, tlwt is, in landscape (horizontal) mode. 

-n name Use name to label the output. If this option is not given, the "I'or user:" 
field is lell blank. 

-b banner Use banner in the "File:" field instead of the filename. 

'h hostname Host name to use instead of "V-System". 

-m mode Print mode. I'ossible modes are 



Line printer (the default), l-'or printing ordinary text 
files. 

DVl. For printing TeX output. 
Press. Not. implemented. 

HP2680a. For files in HP2680a "spool file" format. 



•w 



File is in Uie Sail (**WA1TS") character set instead of sumdard ASCII. 
(Line printer mode only). 



If no filenames arc given, boise reads its standard input. 
Change directory: change the current context 

Lets you play a game of checkers against die workstation. This is also a good 
demionstration of Uie vgts' graphics capabilities. See chapter 10. 

Clears the pad. 
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context 

CP 

copydir 



dale 

date 

define 

debug 
destroy 

dopar 

doseq 

draw 
echo 
fexecutc 

heip 

internctscrver 
iphost 

iptelnct 



Prints an expanded name for the current context, or if a context name is given, for that 
context. Also known as pwJ (print working directory), by analogy with Unix. 

Copy the first file to the second file. 

Invoked as: 

copydir fromdir todir 

copies the fromdir directory subtree to todir. todir must previously exist New files are 
created in a default mode, while the mode of existing files (being updated) is left alone. 

Distributed version of yet Another Layout Editor is a VLSI layout editor diat provides 
graphics editing of SILT chip descriptions. Documented in a Stanford CSL Tcclinical 
Report 

Prints the date as maintained by the local workstation kernel, and as maintained by the 
session host. The kernel-maintained time on a workstation is set from a time server when 
the exec is started. The command data -s sets die local time to the network time. 

Defines one or more local names for a context. The first argumcnt(s) are tlic new names to 
be defined. The last argument is a context name, specifying the value to be given to the 
new names. 

'Hie V debugger. See chapter 6. 

Takes the name of a team (or any suffix) as an argument, and sendf a message to the team 
server asking it to destroy that team. If the argument begins with tlie characters Ox, it is 
taken as a process id, and that process is destroyed. 'Hiis is useful for killing processes run 
in the background. 

A program vSimilar to doseq, except tliat it allows the executions of its command argument 
take place in panillcl on difTcrcnt hosts, 'ITic program prompts for the names of liosts on 
which to execute tlie command (for each context). If"*" is entered, then the service server 
will select an 'arbitrary' available host. 

This program takes two string arguments: a list of context names, and a command to 
execute. 'Hie command is executed in each context in turn, doseq is ollen useful in 
makefiles, donialce is a synonym for doseq. 

An interactive drawing program tliat runs under tlie VGTS. Sec chapter 8. 
lixhos its arguments. 

Force a command to be executed on tlie server providing the current context, as described 
in section 2.5. 

A program which prints out a little bit of information about the V system, he! p 7 prints a 
list of topics on which help is available. 

A version of tlie Internet Server, as described in tlie V-System Servers manual. 

If given a single host name as an argument, iphost lists all IP addresses corresponding to 
diat host If no argument is given, tlie IP address of Uie local worksuition is printed. 

A multi-window IP/TCP telnet program using the VGTS. This program has a copy of the 
VGTS linked into it so it is only useful under the bare kernel or the STS. Use iptn under 
the VGTS. 



iptn 



IP/TCP-based telnet implementation. It can nm under tlie STS, or in a VGTS window. A 
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listdir 

login 

logout 

ncwtcnn 



piigcmodc 



query 



nn 
serial 



destination host name or address may be given as a command argument; if none is given, 
ipin prompts for one. A liost name is a string of non-wliite-space cliaractcrs stiirting witli a 
non-numeric character. A host address is a string of the form a.b.c,d, where a,b,c and d are 
decimal integers. Both names and addresses may be followed by a dot and a decimal port 
number (with no intervening spaces). 

While connected to a remote host, iptn recognizes a set of commands prefixed by ctrl-t. 
Ctrl-t ? prints a list of all such commands. 

After disconnecting from a remote host, iptn prompts for another host. To exit ipin, enter 
ctrl-c or ctri-2 in response to the prompt. 

If there is no internet server on your workstation when iptn is loaded, it runs one in the 
background. The -1 ting inhibits loading a local server, instead looking for a public internet 
server nmning on another V host. 

The -d flag enables debug mode. In this mode, all transmitted and received telnet protocol 
commands are printed, and all received non-printable characters are printed in an escaped 
nouition. Ocbug mode can be toggled on and ofl* by typing ctri-t d while connected to a 
remote host. 

Lists the names defined in a context, and prints soine information about each. If no 
argument is given, tlie current context is assumed. 

Command to start a session on a computer running a V server. 

Command that terminates sessions. 

Change terminal agents. Takes one argument, the filename of a new terminal agent to take 
tlie place of tlie existing one. All executives running under the old terminal agent arc 
destroyed; the new one will presumably provide means of crcaling a new one. For 
example, ncwtcnn sts replaces die vgLs witli tlic Simple Terminal Server, which docs no 
graphics but simply presents the workstation as an ascii terminal. If no argument is given, 
it dcfaulLs to "vgts". Watmng: If ilie named program is not in fact a terminal agent, you 
will probably lose control of your workstation. 

Enable or disable paged output mode in tlie current executive. Takes one argument, which 
may have one of two values: "on" or "oil". When paged output mode is on. the terminal 
agent stops writing to a pad when the pad fills up with output. The terminal agent then 
displays the message "Type <spacc> for next page" and waits lor the user to issue a 
command which unblocks the pad. The user interface for paged output mode is described 
in section 3.3. 

Prints out the result of performing various 'query' operations. In particular, query 
kernel prints the result of the QueryKernel operation, query conf 1g prints the 
contents of tlie workstation's configuration file, and query ethernet prints tlie result of 
quci7ing the "ethernet" device, query 7 lists the possible options. 

Takes one or more filenames as arguments, and removes each file. 

This program provides a full-duplex conversation between its standard input and output, 
and a device connected to one of die serial ports of tlie workstation. The argument is a 
device name, specifying the line to be opened. It defaults to fdevicpJserialO if omitted. 
Names of tlie form fclcvicejserialn (with n a single digit) can be abbreviated by giving only 
the digit. If die serial line is connected to a modem or a terminal port on another 
computer, tliis program allows tlie Sun to act as a terminal. The flag -b b1 trate can be 
used to specify die bit rate (baud rate) of tlie connection; it detaults to 9600 bps. 
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show 



telnet 

tcstexccpt 

timekcrnel 

tn 



type 

undcnnc 
ved 



Displays a .dv1 file or a .press file. It is driven n^om a menu in tlie invoking pad: by 
selecting tlic appropriate field, you can move around from page to page, with cither 
relative movement, absolute page number or the TcX generated \countO numbers. You 
can invoice it with show filename, or you can set llie filename in the menu. You can 
"scroll" a page by pressing a mouse button inside the view, moving die mouse and 
releasing die button. It handles the TeX generated dv1 files pretty well, tliougli 
magnification is ignored and some fonts are missing. IJiggcst problems: it only handles a 
small subset of press format, tlierc are no good scribe fonts for it, and it is a bit slow. 

A multi-window PUP-based telnet program using die VGTS. This program has a copy of 
die VGTS linked into it, so it is only uscilil under die bare kernel or die STS. Use i/i under 
die VGTS. 

Simple interactive program for testing die exception server. 

Program to measure die Ume for Send/Reccive/Rcply kernel primidvcs. 

PUP user telnet program. It can be nm under die STS or in a VGTS window. /// takes an 
optional argument specifying tlie host to connect to. While running, tire following 
keyboard commands are available: 

ctrl-t c Close Uie connection. 

ctrl-t d Close the connection and delete the VGT, if created by tn. (Only 
available when running with tlic VGTS.) 

ctrl-t e Close all connections and exit from tn. 

ctrl-t o Create a new VGT and open another connection in it (Only available 
when nmning with tlic VGTS.) 

ctrl-t b Create a big (48-line) VGT and open another connection in it. (Only 
available when nmning with die VGTS.) 

ctrl-t ctrl-t Transmit a ctrl-t character, 

/// Is capable either of using die raw Rthernet device on ihc workstation, or going through a 
local internet server. If tlrere is a local internet server, tn must use it, since the kernel 
HUicmet device is single-user. l ''vcn if there is no local internet server when tn is loaded, to 
be compatible with //?///, tn will load a local internet server and work through it if there is 
no public internet server elsewhere on die network dwt could be used by iptn. To force tn 
to use the raw Hdiernct device if it can, invoke it with die command line tn raw 
hostname. 

Only one copy of tn may be run on a workstadon at one tunc. 

Type out one or more files on tlic teiminal. Types a page- full and then' stops and waits for 
input. Pressing (si'ACl'l brings up anodier page, while lRi:ruRN| brings up another line. 
Hit q or tC to quit 

Removes die definiduns of one or more local context names. 

A text editor, similar to Hmacs, which nms under die vgts. Described in chapter 7. 
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4.2. Commands on Session Hosts 

There are also several useful commands that can be invoked on session hosts (usually a Vax/Unix system). 
Use these commands once you have logged into a machine tiirough a telnet connection. Most ot" tlicse 
commands also have versions that run locally on the workstation under the vgts, and the Unix vei-sions can 
also be run remotely under the vgts, using the exec's remote execution feature (section 2.5). 

dale A version of the Yale layout editor tliat runs under the vgts. 

photo Reads and displays a **.sun" format raster file. 

silcdit A program which edits .SIT. format files. SIT., a Simple Interactive Layout program, is a 

graphics editor for logic designs and illustrations. 

silprcss A program which tiikes a .sil format file and produces a .press format file that can be 

printed on the Dover. 
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— 5 — 

Executive Control Commands 



The following commands give the user access to the cxecserver functions. 

checkcxecs Kill off any exec whose standard input server or standard output server has died. 

delcxec Delete an executive, specified by its exec id. The first exec created wlien Uie workstation is 

booted will always have an id of O. 

do Create an exec with a named file as its input lliis file should contain a list of V 

commands* cxacdy as you would type them, one to a line. 

killprog Kill die program, if any, running in die specified executive. 

qucrycxcc Find out the status of the specified executive. Useful mainly for system testing. Sec 

QueryExec in the Program Hnvironment manual. 

startcxcc Create an exec in a new pad. The new exec will have the same context as die exec from 

which startexec was invoked. NOT die [home] context. For most purposes die view 
manager's Create Executive commands are to be preferred over Uiis one, as die view 
manager will not work on an executive created by startcxcc. startexec prints out die exec 
id and process id of the new exec. 
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— 6 — 

The V Debugger 



6.1. Synopsis 

debug [-d] ppogName ppogArgl ppogApg2 . . . 



6.2. Description 

6.2.1 . Invoking the Debugger With a Program 

Debu$ is an asscmblcr-lcvcl symbolic debugger For .r files created by tlic 68000 linker (Id68). It can be called 
as a command to the V exec and Uikcs die following arguments: 

-d If die VGTS is available, then Uiis argument causes an lO pad to be created for the 

debugger which is separate from the one used by die program to be debugged. This option 
is a necessity for programs which read keyboard input via separate reader processes since 
these may interfere with Uic debugger's keyboard input requests. 

progNamc The name of die program to be debugged. 

progArg/? The ndi argument of die program to be debugged. 

'Hius, to debug a program which is normally invoked by: 

progName argl apg2 
one types 

debug ppogName apgl apg2 
If a separate 10 pad Is desiied {for V^is resident euviromimus only) Uicn one would type 

debug -d ppogName apgl apg2 

6.2.2. Postmortem Debugger 

The debugger can also be used as a "postmortem" debugger. 'I*hc V execs (both die Vgts-based one and the 
non-VgLs-bascd one) have been structured so Uiat if an exception occurs in the program currently being run, 
the debugger is automatically loaded and given control. 

6.2.3. Common Usage ' 

A program invoked with die debugger will start out at Uic debugger's command level. IVreakpoinLs may be 
set and the program code and global variables may be examined, 'llic program can dien be started using die 
commands described below. 

A frequent "postmortem" use of die debugger is to obtain a stack trace to find out where a program 
incurred an exception and then quiL I'his is done by typing s after having been transferred into die 
postmorteiTi debugger to get a stack trace, and q to quit: 
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1 oroq aral arnZ 

Bus error on read from address f in process 2ed0024 
Instruction Program Counter Status Register 

1010 10172 10. 

B0> 10174 4880 main+2C extw dO 

Stack trace 

I 



6.3. Commands 

The debugger begins by displaying die line of code at which execution has paused, and tlien gives a period 
(*.') as a prompt. The user can then enter commands using the keyboard. Most commands are terminated 
witli a carriage return: exceptions will be noted in tlie command descriptions. The only characters that may 
be used to erase previously typed input arc backspace (\b) and delete (Dl'.l.). I'he entire line may be erased 
by typing CrUI.-u. When eliminating optional arguments in commands which mkc more than one argument, 
be sure to include tlic correct number of commas for die command. In this way die debugger can delcrniine 
which argument is to be assumed. 

6.3.1 . Definitions 

Within die command descriptions below, an expression is some combination of numeric constants, register 
symbols, globally visible symbols from die pnigram being debugged, and the operators +, and j, 
represcnung 2's complement addition, subtraction, and bitwise inclusive or, respectively. Blanks are not 
significant except in strings. All operations are carried out using 32-bit arithmetic and evaluated strictly left to 
right 

Register symbols arc symbols which represent the various pnxiessor registers. The following symbols arc 



recognized: 




%d0-%d7 


Oata registers 0 - 7. 


%aO - %i\7 


Address registers 0-7. 


%rp 


Kramc pointer (synonym for %a6). 


%sp 


Stack pointer (synonym for %a7). 


%pc 


Program counter. 


%sr 


Status register. 



In all commands except die rcpiacc-registcr (rr) command a register symbol represents die contents of the 
specified register. In Uic replacc-rcgister command it represents die address of die register specilled. 

Globally visible program symbols are names of program routines or global program variables. 

'Hie single character (dot) is treated as a symbol representing the last memory location examined. Its 
value upon entrance to die command level of die debugger is set ft) die current value of die program counter. 

6.3.2. Execution Control Commands 

expression^ number, b .' 

Set breakpoint number {in die range 2- 15 decimal) at expression, expression must be a legal 
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expression, g 
expression., gb 

expression, x 
expression, y 

XX 



sp 



instruction address. If number is omitted the first unused breakpoint number is used. If 
expression is 0 the named breakpoint is cleared, or if number \s omitted tlien all breakpoints 
are cleared. If expression is omitted all breakpoints are printed. Note: if expression is 
omitted thQn number must also be omitted or must be preceded by a comma in order 
distinguish it from being interpreted as the expression argument. 

Go. Start or resume execution at expression. If expression is omitted, tlien start execution 
at the current pc value. 

Go past breakpoint. IJkc go with no argument except that if we are presently stopped at a 
breakpoint, dicn expression counts the number of times to pass this breakpoint before 
breaking. If expression is omitted, then 1 is assumed. 

Execute die next expression instructions, stiirting from the current pc and printing out all 
executed instnictions. If expression is omitted, tlicn I is assumed. Note: traps are executed 
as single instrucUons; i.c. the instructions executed in a trap routine arc not displayed or 
counted. 

Same as x except that subroutine calls arc executed as single instnictions; i.e. do not 
descend into the called subroutine. 

XX is a synonym for y 

A synonym for x, except that each instruction executed is displayed on the same lijie as die 
command, providing a more compact display. No carriage return is needed to terminate 
diis command; tlie semi-colon triggers execution. The typeout mode referred to in tlic 
command descriptions is described under tlie t command. 

Toggle the flag diat determines whether the whole team stops at an exception or just die 
pr(]cess that incurred die excepdon. The debugger's default behavior is to stop the whole 
team when an exception occurs, not allowing any of its processes to proceed until one of 
the above Hxecution Commands restarts die team. (Of coui-se, at diat point ANY of die 
proc(»ses could resume execution -- i.e., single-stepping one process could allow another to 
execute indefinitely.) Ifdiis command is typed, an exception in any one prtKiess will not 
halt any of die other processes on die team. Typed ag;iin, die debugger goes back to its 
original behavior. 

Quit. Hxits Uic debugger and kills both Uic debugger and the program being debugged. 



6.3.3. Display Commands 

The following commands arc executed immediately without waiting for a carriage- return (CR) to be typed, 
and Uicir output overwrites the current line. ('ITiis provides a more compact display format.) 

expression/ 
expression\ 

/ 
\ 

m 

expression®. 



Display die contents of expression. The typeout mode used is determined from die 
prognini symbol table and tlic current typeout mode. The value of dot is set to expression. 



Display die contents of dot after having respectively incremented (/) or decremented (\) it. 
The typeout mode used is determined from the program symbol table and die current 
typeout mode. 



Display die contents of the memory locations pointed to by die value of dot or expression. 
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respectively. The typcout mode used is determined from die program symbol table and 
the current typcout mode. The value of dot is set to die address of Uic memory location 
just displayed. Note diat %pc will yield die contents of die memory location pointed to by 
the pc register (i.e. die current instruction) and diat %pc@ will attempt to place an 
additional indirection on that memory location. %pc@ is almost always an invalid 
reference. 



expression^ Display the value of dot or expression, respectively. 

The following display commands arc executed when a carriage-return is typed, 
d Display the contents of all the registers. 

s Print out a stack trace describing the chain of subroutine calls and their parameters. 

Warning: die debuggers stack trace examines the values of parametci-s as dicy currently 
exist on the stack, not as diey were when Uic routine was called. Routines which change 
Uic values of Uieir parameters will similarly affect the stack trace output 

expression, nunilines, n 

Display die next mtmlines memoi7 locations, suirting at expression. If expn^ssion is 
omitted, dicn display starts at dot. If numlines is omitted, Uien 24 lines are displayed. 

expression, numlines, p 

Display the previous numlines memory locations, starting at expresvon. If expression is 
omitted, then display starts at dot. If numlines is omitted, dien 24 lines are displayed. 

type, t Temporarily set typcout mode to type where type is one of: 

'c' type out bytes as ascii characters. 

'h' type out bytes in current output radix. 

'w' type out words (2-bytes) in current output radix. 

T type out longs (4-bytes) in current output radix. 

V, slrLenglh type out strings. Set die maximum length of strings to bo strl.engih. 

'Hie maximum siring length determines how far Uic debugger is willing 
to look for the end of a string, which is assumed lo be a '\0' byte, h'or 
programming languages such as Pascal which don't terminate Uieir 
strings with a '\(V byte diis limit is important to prevent endless string 
searches, 'ITic string maximum length is sticky (i.e. it need be set to the 
desired value only once). The default value is 80. 

T type out as symbolic assembler instructions. 

Note Uiat die type characters must be surrounded by single quotes. If no argument is 
supplied dicn Uic default typcout mode is used. This mode tries to vSct Uie typcout mode 
based on die type of symbol(s) being displayed and uses T fomiat when die mode is not 
obvious. The new typcout mode stays in eftcct until execution is resumed with one of die 
Hxecution Control Commands. 

type, it PermancnUy set typcout mode to type. 'ITic typcout mode is set to die default typcout 

mode if type is omitted. 

base, ir Set the input radix to base. If base is illegal (less than 2 or greater dian 25, decimal) or 

omitted, dicn hexadecimal is assumed. (This is the default radix.) 
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base, or Set the output radix to base. If base is illegal (less than 2 or greater than 25, decimal) or 

omitted, then hexadecimal is assumed. ('Hiis is the default radix.) 

offset, of Set the maximum offset from a symbol to ojjfsei. If ojjset is illegal (less than 1) or omitted, 

then hexadecimal 1000 is assumed. (This is the default offset.) This command is useful 
when examining areas of the team, such as the stack, which arc more accurately labeled by 
hex addresses Uian by symbol + offset notation. 

charcoutm si Set the maximum number of characters in a symbol which will be displayed to charcount. 

If charcount is illegal (less than 1 or greater than 128) or omitted, tlien 16 is assumed. 

6.3.4. Replacement and Search Commands 

expression!, expression2, type, r 

Replace the contents of the memory location specified by expression! with expression!, 
expression! is interpreted to have type type. Note: It is not currently possible to replace 
strings with this command, and instructions should be specified" in U)-bit quantities and 
replaced with type 'i'.. \\ expression! is omitted, then tiie value 0 is used. 

register, expression, rr 

Replace the contents of the specified register with expression. If expression is omitted, then 
the value 0 is used, expression is interpreted to be a 32-bit quandty. 

expression, lowlimit, lii^Jilimit, type, f 

Search for (find) pattern in the range lowlimit (inclusive) to highlimii (exclusive). 
expression is interpreted as an object of type type. Objects are assumed to be aligned on 
word (2-byte) boundaries except for l-byte types and strings, which are aligned on byte 
boundaries. A mask (set with the mask command) determines how much of the expression 
is significant in the search, unless expression is a string constant. The llrst three arguments 
to the search command are sticky: thus if any of them are omitted lhc!i their prcvit)usly 
specified value is used, f is tlic only debugger command which allows the specification of a 
string constant as expression. A string constant is delimited by the character " on cither 
side: lo use " in die string itself, precede it with a \, An example ofii string is: "This is a 
string with \" in it". The typeout limit of strings determines how much of die string is 
significant in the search, not tlie search mask. 

expression, m Set the search mask lo expression. If expression is omitted then 0 is used. -l,ni forces a 
complete match, f,m (that's hex 0 checks only the low order 4 bits, 0,m will make the 
search pattern match anything. 

6.3.5. Help Commands 

h Print a brief description of each of the debugger's commands. 

w Print a set of internal debugger statistics. This was implemented for Uie convenience of Uie 

designers and may change frequently in content and format. It replaces the obsolete qq 
which, due to die debugger's unsophisticated command pai-sing will behave exactly as does 

q. 



6.4. Bugs 

The debugger as it is currently implemented lias some "features" one must be aware of. 

Currently, each instance of the debugger can debug only one team at a time. Programs that create imd load 
new teams will cause problems because Uie debugger assumes diat it is always dealing with die same program 



V-SYSn-M 5.0 RI-n'RI-NCl- MANUAL 



COMMANi:)S 



34 



THEVDl'BUGGliR 



image. 

If a breakpoint is encountered anywhere between the receipt of a message and a later attempt to call 
RcrcadMcsscigcO on that message then the breakpoint exception will destroy the message value, yielding 
garbage in the subsequent call to RcreadMessagc(). 

The debugger assumes tliat any trace trap exceptions have been caused by Its own single-stepping 
mechanism. Though it will recognize the first one, and print an error messiige, subsequent trap exceptions 
can cause intolerable behavior. 

The stiickdump routines depend upon knowing the string names of the kernel routines to produce correct 
stack traces which include those routines. Right now, tliis list is being kept up to date by hand. 

Putting breakpoints in code which is shared by two or more processes can be hazardous to your mental 
health. 
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Ved: A Text Editor 



Vcd is the V system text editor. It runs entirely on a Sun workstation, using a session liost only for file 
service. Its basic keyboard commands arc a subset of Hmacs. However, the mouse adds a whole new style of 
interaction with tlic editor. The multiple window capability of the VGTS is put to good use, as well. And the 
user will quickly notice that it responds much faster than Kmacs on a normally loaded system. 

Vcd manages one or more editing windows. Hach window is thought of as a viewport onto a buffer of text, a 
continuously accurate display of some portion of that text. A change to the buffer is followed immediately by 
a corresponding change to the display. In each buffer tliere is a cursor, which is guaranteed always to be in 
the portion of the text displayed. Kiich buffer normally has a filename associated with it, tlic file from which 
it was read or tlic file to which it was most recently written. 



7.1. Starting Up 

Vcd runs under the V system executive, which is invoked as described in the previous chapter. Once inside 
the executive, type 

ved 

or 

ved filename 

The filename can be in any of the forms recognized by tlie V exec ~ a relative patlmame, an absolute 
pathname, or [.session host] followed by a patlinanic of cither type. Vcd prwccds to read in the named Hie 
given, Uicn requests a pad, its llret editing window. This is indicated by the mouse pointer, which changes to 
tlic word "Pad". Move die mouse to the desired upper left corner of die pad and click any button. The pad 
will appear, and in it die first .screenful of text will be displayed. The pad in which vcd was invoked is 
reserved for displaying error messiiges and typing special text, such as filenames or search strings, which is not 
to be inserted into any buller. In normal use it is convenient to shrink this window down to a few lines at die 
bottom. 

At die top of die edidng window, dicre is a banner. When the banner is inverted, then diis window is 
selected for input either by die mou.sc or die keyboard. The banner specifies die ved window number which 
is used by die window selection command (described in section 7.10) and die Vgt number (see section 3.2). 
'Hie rightmost area is reserved for die file name asswiated with this window. If die file name has an asterisk 
(*) prefix, then vcd diinks diat diis buffer has been modified since die last write or save of the specified file. 

As an added feature, diere is a inverted line of text at die bottom of every vcd window. This is the fixed 
menu area of die window. It can be used to enter some Ircqucntly used commands using die mouse instead 
of die keyboard (a full description of the fixed menu is in scxtion 7.6.2). 



7.2. Motion 

The following commands are available to move die cuj-sor within a file: 
The four arrows Move diccursor in die direction indicated. 
tF, tB, backspace 
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Horizontal cursor motion. 

esc f, esc b, esc backspace 

Word-oriented cursor motion, esc-f goes forward to ttie end of a word; csc-b and esc- 
backspacc go bacic to ttie beginning of a word. 

tP, tN Vertical cursor motion scrolling if necessary. 

tA, tE Cursor to beginning, end of line. 

esc comma, esc period 

Cursor to top, cursor to bottom of visible region. 

Cursor to beginning, end of text. 

Get out of special states. Whether you have just typed Escape or tX and didn't want to, or 
arc busy typing a search string, or whatever, tG will get you baclc to the nonnal state. 

Quit the editor. If there are any modified buffers, you will be asked if you want to save 
them. Here and in similar cases, if you arc warned and tlicn decide you don't want to do 
tlic command at all, type tG to escape back to nonnal editing. 

Also quits, but first asks for cunfiiTnation, which should be answered with "y" or Return if 
you mean to quiL tC is kept for Unix compatibility, protected with a mcssiigc because a 
multi-window edit can take some time to set up, and should not be at tlie risk of a single 
keystroke. In the future, tC is intended to serve a "quit local edit" flmction, when ved or 
something like it is a service available to programs like mail and send. 



7.3. Paging and Scrolling 



tV, esc v Page down, page up. 

tl. Redraw tlic display. 

PFl Scroll -- move the viewport down one line relative to the text 

PF2 Scroll backward ~ move Uie viewport up one line relative to the text 

tZ, esc z Synonyms for Pl-'l, PM respectively. 

esc PFl Moves tlic viewport 1/2 page down the text ~ half a tV. 

esc PF2 Moves the viewport 1/2 page up the text. 



esc downarrow, esc uparrow 

Synonyms for esc PFl, esc PFl. 



7.4. Simple Editing 

. Typing any printing character, or TAB, inserts the character typed. Other special characters are handled as 
follows: 

tD Delete forward from the cursor - the character under tlic cureor. 

OBL IDelete backward from the cursor, 

esc d Delete word forward. 



esc <, esc > 
tG 

tXtZ 
tC 
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esc DEL, esc h 

Return 

to 

tK 



tY 

escy 
Linefeed 

CSC Tab 



tQ 



Delete word backward. 

Insen: a Linefeed, not a CR character gets tlie desired effect 
Insert a Linefeed, leaving tJie cursor before it 

As in Emacs. Delete the contents of one (logical) line, or the carriage return on an empty 
line, into ttie killbuffer. A sequence of tK commands uninterrupted by any other 
command causes tlic whole section thus deleted to go into tlie killbuffcr. tK after any 
other command restarts tlic killbiiiTcr from scratch. 

Yank - insert contents of tlic killbuffer at die cursor. The killbuffcr is unchanged. The 
cursor ends up at the beginning of the insertion, and the Mark (see below) ends up at die 
end. 

Yank, but without disturbing the Mark. The cursor ends up at tlic end of the insertion. 

Insert a newlinc (Linefeed) and dien indent the new line to die indcntadon of the previous 
line, using tiibs where possible. If the previous line is empty, it will look up until it finds a 
nonempty line and use that as the standard of indentation. 

Add indentation to Uiis line equal to die indentation of die previous line. Intended use: if 
you type Return and wish you had typed Linefeed, diis will make up die dilfcrence. 

Quote the following chaructcr. Allows you to insert non-printing characters (such as the 
useful tL, fonnfccd, which forces a page break on most printci-s) into die text. 

Quote the following character and insert it with die high bit set tQ and t\ are die only 
exceptions to die tO command: diey will quote a following tG, but that simply means die 
insertion of a character, which can easily be deleted. 



7.5. File Access 

Whenever vcd writes a file, it preserves die previous version of that file (if there was one) by renaming it to 
its former name followed by ".BAK". 'ITius myfile.c becomes myfilccBAK . 



tXtV 

tXtS 

tXtW 

tXtl 

esc - 
tXb 

tXc 



Visit a tile, whose name will be requested. 'Hie new file replaces the current one, so if die 
current buiVcr is modified you wilt be asked before proceeding. 

Write die bulTer back to die file from which it was read. 

Write die buffer to a file whose name will be requested. 

Insert file at die cursor. You will be asked for the file name. Cursor and Mark arc set just 
as in tY above. 

Forget that the buffer has been modified. 

Toggle the .HAK safety feature. Creation of .HAK files makes file writing take about 4 
times as long as it otherwise would, so if you really want diat speedup, Uiis will turn off die 
making of .BAK files. tX b again will turn it back on. 

Change current context 'ITiis command allows a user to change die way character string 
names arc interpreted. A context is similar to a directory in diat it defines which object is 
associated with a name. The file name represented in the banner of die pad should always 
be context independent (See section 2.3.) 
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7.6, The Mouse 

The mouse offers an alternative way of doing several common editing functions, such as placing tlic cursor 
and deleting or moving text. The mouse has two flmctions: fixed menu selection and editing. 



7.6.1 . Editing With the Mouse 

Left button Click and release It at any character in the text: sets the cursor at that character. Click it at 
one character, move tlie mouse to another point in tlie window, and release: selects tlie 
text between the point of clicking and the point of relciise. While you are moving the 
mouse with die left button held down, the region which would be selected if you released it 
at this moment is displayed in inverse video. When you release, your selection is defined 
and remains displayed in inverse video. Carriage returns are invisible, so die selection of a 
carriage return is shown by black space from the end of the text on that line to die end of 
the window. Note that a selection and a normal cursor are mutually exclusive. The 
importance of this will become apparent below. If you have a selection and click die left 
button, with or without moving, die former selection is deselected and a new cursor 
position or selection is chosen. 

Middle button When you have a selection, clicking die middle button deletes it into the killbuffcr. If you 
have no selection, nothing hiippcns. The position of llic inousc is irrelevant. 

Right button Brings back the contencs of the killbufTer and makes it selected. If dicrc is nothing in the 
killbuffer, nothing happens. If there was a selection already, its contents arc swapped with 
the contents of the killbuffer. If Uicrc was no selection, die contents of tlie killbuftcr 
replace die cursor. 



7.6.2. Fixed Menu 

The fixed menu diat appears at die bottom of every vcd window provides the user with mouse t)rientcd file 
perusal capabilities. Clicking the middle or right mouse buttons in the llxed menu area will execute tlie 
command diat is nearest the mouse cursor. All the commands in die menu could be entered from the 
keyboard, Uierefore diey are not described here. Refer to die sections on searching, scrolling, and regions for 
descriptions. 

In the fixed menu area, the semantics of the each of the buttons differ. The middle button (in gcncrni) 
means forward whereas the right button means backward. I'or instiuice. clicking tlic middle button at the 
hull-Page command will cause die window to be scrolled forward one full page and die right button will cause 
a reverec scroll, llic commands Hair-Pagc, Scroll-Lliiu, and Search behave in diis siime manner. The Tag 
command has cxacdy die same semantics for both buttons. Mark/l'oint is die only "different" command; in 
it, die middle button causes a jump to the Mark and the right button sets the mark at die point. Note diat tlie 
left button has no effect on menu selccdon. to maintain continuity during dynamic selccdon. The Search and 
Tag commands will eidicr use die selected string as Uic pattern or prompt die user for one in die case of no 
selection. 



' 7.7. Searching and Replacing 

tS Search for string. Prompts for a string, and finds die first instance of diat string after the 

cursor. Prints "Not found" if dicre is no such instance. If you type Return without typing 
any search string, die previous search string is used - tS Return is equivalent to PF3 as 
described below. Here and elsewhere, a newlinc can be inserted into tlie search string 
using die Linefeed key. It is echoed as an in vei-se- video backslash. Non-prindng 
characters can be searched for, and are ahoed as like "tA". If the search succeeds, the 
string found is selected, and several special commands (described in The Right Hand and 
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die Left, below) arc available. In particular, typing s will repeat the search. 
tR Reveree search. Just like tS but searches backward. 

PF3 or esc s Repeat search. Forward search for the string most recently used in a tS or tR command. 
Works regardless of wlicther there is currently a selection or not. 

PF4 or esc r Repeat search backward. Like esc s but searches backward. 

esc q Query Replace, Prompts for a search string, then a replacement string. Then searches till it 

finds the search string, and selects that text Type y (yes) to replace, n (no) to leave it alone 
and go on. Other options are described below. These special commands are available 
whenever there is a selection, so Query Replace is easily re-enterable. Just use PF3 to find 
and select tlic next instance of the search string, and away you go, 

esc g Go to line. Prompts for a line number, and moves the cursor to the head of that line in the 

file. The first line is numbered I. If the number is too large, it will go to the end of text 
and notify you of the true line number there. 



7.8. The Right Hand and the Left 

When dicrc is a selection, Uic cursor is not in a single spt)t, so it would not make much sense to insert 
character at the cui"sor. So various printing characters are used as special sclcction-rnode commands. The 
most biusic of these commands arc all assigned to left-hand keys. Thus one possible mode of operation is for 
the user co have his right hand on the mouse, selecting things, and his left hand at the usual place on the 
keyboard, giving commands which arc not available on the mouse buttons. Others of these commands arc 
designed for use with the search and replacement facility. 

Non-printing characters other tlian those described below deselect, then perform their usual function as if 
the cui"Sor had been at the beginning of the selection. 



space bar lOcsclect The cursor lands at the beginning of tlie selection, AH printing characters not 

mentioned here also have tliis effect, but die space bar is recommended. 

Tab IX'selcct, but die cui-sor lands following the end of the selection. 

d l>:ictc. Hxactly identical to die middle mouse button. 

c Rxchange. Hxactly identical to die right mouse button. 

c Copy in place. A copy of die current selection is inserted right after it, and becomes the 

new selection. 

g Grab. The current selection is copied into die killbuffcr without dclcdng it 

s Search for the next instance of die selected string. This becomes the search string, as used 

in future Repeat Search or search-and-replace commands. 

r Reverse version of s. 

PfO, PF4 Repeat search dicy perform dicir usual ftinction, using die stored search string rather 

than die current selection. 

PFl, PF2 Scroll as usual, but unlike other commands diey do not deselect unless the selection is 

being scrolled oft* die screen. 

tL Redisplay, with die selection near die top of die screen. Good for long selections which 

run off die bottom of die screen. 
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y Yes replace. Replace the selection witli the stored replacement string. 

n No don't replace. Search for tlic next instance of the stored search string. 

backspace Undo replacement. Search backward for tlic first instance of the replacement string and 

replace it mth die search string. The resulting string is selected. 

Y Yes replace but don't move on. The selection is replaced and die result remains selected. 

u Undo in place. The current selection (which hopcftiUy is die replacement string) is replaced 

with the search string. 

S Search for next instance of the replacement string. 

R Reverse version of S. 

q Start query replace. Takes the current selection as the search string, and prompts for a 

replacement string. Replaces the current selection, and goes on to tiie next instance of it, 
just as "y" would do. 

Q Set replacement string. The current selection is copied into the replacement string. This 

makes it possible to alter a Query Replace in mid-flight, 

7.9. Mark and Region • 

Ved maintains an invisible point in the buffer called Mark. Until otherwise set it is at the beginning. It can 
be set by tXtM or Control-® (Control-spacebar is die Siime as Control-^' on some keyboards). "Region" 
refcre to all die text between Mark and the cureor. The following commands use diese concepts: 

tX tM, t@ Set die Mark at die current cursor position. 

tX tX Exchange Mark and cursor (changing die display if necessary to keep die cursor on die 

screen). 

tX tK Kill Region. Region vanishes and becomes the killbuffer so this command can be 

undone with tY. Note thai in Unix F.macs this function is normally bound to tW. 

tX tR Write Region. Prompts for a file name, and writes Uie region into dial lllc. The buffer is 

unchanged. 

7.10. Windows and Buffers 

Ved is normally started with one editing window, but it can support several. Fach editing window is 
associated with a separate editing buffer, which includes die text, cursor position, selection if any, associated 
filename, and whether diis buffer has been modified. Multiple windows on the same bulTer arc not 
supported. Since die correspondence is one to one, hereafter we refer to "window" meaning "window and its 
associated buflcr". At any lime one window is selected for editing, and is foremost on the screen. Window 
selection can be changed by clicking a mouse button in an unsclected window, or by pressing the appropriate 
number key on the keypad, Windows arc numbered, starting at I, in the order of dieir creation. 

The search and replacement strings and die killbuffer arc universal across windows. Thus it is possible to 
kill some text in one window and yank it into another. It is likewise possible to search for a string in one 
window, dien select another window and repeat-search on the same string. 

The window from which ved was invoked is special. It cannot receive input except during certain 
commands, at which Ume it is selected automatically. It is never receptive to mouse input 



V-SYSTI-M 5.0 RW'MRI-NCI' MANUAL 



COMMANDS 



WINDOWS AND BUFFERS 



41 



tXg 



Get file. Prompts for a file name, and reads it into a new window. If no flic name is given, 
creates an empty window. Here and in all other cases, when a window is to be created the 
mouse cursor will change to "Pad" and let you indicate where tlie window is to go. If you 
abort the pad creation by pressing all three buttons, the command is aborted. 



tXd 



Delete the airrent window. Will warn you if it is modified. The next lower numbered 
window becomes selected. If tlic last window is deleted, ved quits, because it cannot live 
witliout a selected window. 



tX a 



tXm 



tXl-tX9 



tXy 



Yank to window. The killbuffcr is copied into a new window. 

Pull Apart Kills tlie Region in the current window and transfers it to a new window. 

Merge windows. Asks the user to indicate a secondary window, and transfers its contents 
into the current window at the cursor position, 'llie secondary window is then deleted, 
llie secondary window is indicated by clicking the mouse in it 

Select the corresponding window. 



Mouse click in any unsclcctcd window 
Select it 



7.1 1 . Crash Recovery 

In an ideal world, this program would never crash. But in fact it sometimes docs - but it is so designed tliat 
it has to crash in two stages to lose your text Normally a crash only breaks the first stage. In which case you 
will get the message 

Edito-r crash! Shall I try to save this buffer? 

If you have any changes, and you value them, and the crash did not come during a save, it is probably a good 
idea to answer "y". A .BAK file will be made, so the danger of total loss is small. If this succeeds you will be 
asked 

Try to continue?. 

If you answer "y", the inner cditpr will be recreated with the buffers just as tliey were. For some display- 
related errors, a tL at this point will set everything right However, you arc on shaky gn)und, and tlie best 
tiling to do first is Siive any modified bulTcrs in other windows. 

If you are dumped into tlic debugger by an editor crash, the debugger command Suicide, g will destroy 
the process tliat got tlic exception. This will usually activate ved's crash recovery lacility. as described above. 

Ved tries to detect the cases in which it runs out of memory. In some activities, such as reading in a file, it 
will simply refuse. In others, such as a kill or an insertion, you will get the message 

Out of memory t Please do one of the following: 
Pick a window to delete 
c - continue (after you free something) 
q - save and quit 
tC - quit without saving 

Ved cannot pnxrecd without more memory, and cannot exit gracefully from tills activity, so you have to help 
it out To pick a window, select It with one mouse click and signal it with a second click. It will be saved if 
modified, then deleted to reclaim its storage. If you have anything else going on on your Sun, you can delete 
a view or terminate a program or delete an exec to free some storage. After doing so, type c to continue. If 
this won't work, type q to try to save everything and quit gracefully. It will save tlie current bu (Tor last, trying 
to avoid tlie dangers of saving a hali-modificd text tC is a last resort a quick and dirty quit 
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VED: A TEXT EDITOR 



7.1 2. Hints on Usage 

Ved has no repeat factor like the tU of Emacs. Use tJic hold-repeat feature of the arrow keys to move the 
cursor around - they happen fast enough that this is ratlier workable. '1 ake advantage of tlie scrolling 
features you will quickly become addicted to the convenience of getting your material centered on tlie 
screen exactly as you want it. When making scattered changes, you will find the mouse very helpful. 
Arrow-repeat will get you there fast, but a mouse click will get you there now. Likewise sclect-and-deletc is 
the fastest way to delete a small piece of text so you can type something to replace it. 

Ved is almost too large now to run on a 256 K workstation. Use it only with one or two page files on such 
workstations. Attempts have been made to catch the event that ved runs out of memory, and give you a 
chance to save, but this is not reliable. . 

If you get into a weird state, try tL, it often restores sanity. If that fails, a save may work anyway ~ it uses 
only the textual data structures, and it is the display, structures that usually foul up. 

Hsc followed by a number key invokes one of the debugging routines. Avoid them. 
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Draw: A DrawingEditor 



The Draw program is meant to fill a specific void in the V-System software. Specifically, the lack of an 
analog for the Alto Draw program is addressed. The V Draw program is not identical to its Alto counterpart, 
although as much symmetry as possible was included. If you have any questions about the behavior of tlie 
program, try using the Help command. It will (hopefully) provide some meaningful information. 

This program runs under the vgtscxcc only. Since it uses splines, it will not run under the small version of 
the VGI^S configured for 256k Sun workstations. 



8.1 . Conceptual Model 

'ITie conceptual model behind diis program is one similar to a person drawing regular objects on pieces of 
paper. The drawing pen has a number of dilTercnt nibs (tips) which can be selected. Similarly, die "ink" and 
fill pattern used to shade areas also comes in several flavors. The ink can be citlier transpari-nt or opaque. 
If transparent ink is used to fill an object, anything under the object will show tl\rough. If opaque ink is used, 
underlying objects will be obscured. I'he Bring to Front (raise) and Push to Buck (lower) commands are 
useful for shuffling which objects lie on top of each other. Hach object lies endrely in its own plane, so it is 
impossible to create works similar to tliose popularized by M. Eschcr. 

Curves are generated using B-Splines of various orders. By default, all curves are of order 3, and thus use 
quadratic inteipolation. The Alter command can be used to change die order of the interpolating splines. 
Automatic filling (shading) of closed objects (specifically, closed curvi-s, closi-d polygons, and certain 
Tl-MPLA'n-S) is possible. 

A GROUP is a collection of cxistings objects lumped together and treated as a single unit. Groups are useful 
for replicadng completed symbols and figures in several places. 

A variety of standard shapes are provided, and are referred to as 'n-iviiM /vn-s. rcmj)lates for Arrowheads 
(open and closed, wide and narrow) exist, as well as templates for rectangles, circles, and ovals. I'ach object 
on the screen has a type, st) while it is quite possible to create a recunigular closed pt)lygon which appeai-s 
identical to a rectangular template, they are of distinct type. This is Important to bear in mind because 
whenever you are asked to select an object on tlie screen, tlie program will only examine objects of a certain 
type, and so some confusion might arise when the program doesn't find the tiling you are right on top of. 



8.2. Screen Layout 

When Uie program is first invoked, it will create two new windows on the screen. The large empty one is 
tiic main drawing area (known as "drawing urea" to llic VgLsexec), and tlie smaller one is the connnands 
window (known as "draiw menu" to the Vgtscxcc). The drawing area is zoomable (for instructions on how to 
use the VgLscxcc, see tlic V Commands Manual), and tlie grid spacing available at normal magnification is the 
same as that used by tlie program. Since the program has no way of knowing what magnification you are 
using, it aligns to the unzoomed grid values. The VGTS will place grid points at a constant separation, 
regardless. of magnification. You may create additional views, move existing views, etc., to your siitisfaction. 
The default drawing area is in tlie proportion of 8.5 by 1 1, and centered. A frame is put around the actual size 
of a drawing page to provide some reference points if you zoom tlic view or change its centering. The frame is 
normally not visible, as it lies entirely outside the default view. It will not appear in any output. 
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DRAW: A DRAWING EDITOR 



The Menu window is divided into three separate menus. One consists of action commands (Rotate, Scale, 
Move, Copy, Oraw, Alter, Krasc, Push to Back, and Bring to Front), which place the program into a state 
where it is waiting for you to specify certain actions. Typically, you will need to specify an object type (ALL 
OBJECTS, ITiXT, OPliN CURVa CLOSOD CURVE, CURRENT OBJECT, OPEN POLYGON, CLOSED POLYGON, GROUP, 
or Tl-MPLA TE) and then some data points. A second series of menu options runs along the bottom of die 
menu window. 'Iliesc are the commands which control various defaults within die program. For example, If 
you wish to change the default font which new text is displayed in, select the Text default option in the lower 
left corner of tlie menu (not the object type TEXT under tlic "Objects" column), and make the desired 
selection in the popup menus which will appear. The third section of the Menu is the list of permanent menu 
selections (Exi t, Hel p. Mi sc. Undo, Abort, and Done). These commands arc valid most of the time. In 
particular, you can always hit He 1 p. 

The original window which you used to run tlie draw program will serve as a combination history log and 
prompt file: The program will print many prompts in this window, telling you what it expects you to do next, 
and what it didn't understand of your last action. When you ask for Help, it will appear in this window. 



8.3. Command Input 

The program accepts all command input through the mouse. Clicking the mouse near a command in the 
Menu is sufficient to indicate to the program that you wish to specify Uiat command. Clicking the mouse in 
the drawing area will citlicr specify a datii point or a command, depending on which mouse buttons arc used. 
More on that later. Sometimes input is required from the keyboard. Due to limitations of the VGTS. when 
the program Is requesting input from the keyboard, clicking die mouse wilt have no immediate eflcct. Once 
die program gets around to asking for mouse clicks agiiin, all of the saved clicks will be processed. 

Occasionally the VGTS will have difficulties synchronizing communications. 'ITiis almost invariably occurs 
when you hit a character on the keyboard while the program is expecting a mouse click. When this happens, 
a message similar to 

Sync error - Expected 037, got 040 

will appear. After Uiis happens, Uiings usually get a little strange. I1ie program will stiirting complaining 
about 

Internal Rrror: Bad mouse buttons 170 at (5, 89) 

(maybe with other numbers) or more commonly 

Missed! Plea.se select a menu command. 

and refuse to recognize anything you do as intelligible. Do Not IDespair!! The remedy for diis is to 
deliberately force more sync errors (by alternately typing a character on the keyboard and attempting 
innocuous commands with tlie mouse, like I Iclp) until a full cycle has been completed. This typically requires 
you to force tiirec more synchroni/adon errors, and dien everything will be completely functional again. 



8.4. Control Points and Sticky Points 

When you create a curve, you will be asked to specify the Control Pt)inLs of Uie spline. These points are the 
places which you wish die curve to pass near, llic more control points you put in one place, Uie nearer Uie 
curve will come to that place. Also, placing multiple control points at a single point will make tlie curve much 
"sharper" at that point. Except for the end points of open curves, and multiple control points, the curve will 
not pass dirough any of die control points. 

Sticky points (similar to Knots) are points which actually lie on die curve. They are calculated by die 
program to help you with die alignment of objects. There will be the same number of control points and 
sticky points on curves. Polygons are a special case, in that since the control points of a polygon actually lie on 
tlic "curve", die program considers them to be sticky points too. This means diat tlie sticky points on 
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polygons Uc at the corners and in the middle of each edge. Sticky points for bounding boxes (e.g., for text 
objects) arc the same as those for polygons. 



8.5. Mouse Buttons 

When the mouse is clicked inside the Menu, it is unimportant which mouse buttons you use. Within a 
popup menu (a list of choice which "pops up" after you do something), you can abort by cither clicking 
outside the menu or by pressing all three mouse buttons down and releasing them. In general, you don't have 
to release (or press) the buttons all at once, but the mouse position is biised upon where the cursor is when 
you release the last button. 

Clicking die mouse inside the drawing area can cause one of several different commands (and mouse 
locations) to be used by the program. The use of mouse keys within tlic drawing area is as follows: 



Buttons Effect 



X - - Specifies a data point right where you are pointing. 

- X - Requests the program to find a sticky point. 

- - X Requests the program to use the nearest grid point. 
XX- The Almost Done command, (see below) 

X - X Requests that a Checkpoint be made. 

-XX Equivalent to the ••UNDO" command. 

XXX Equivalent to the "ABORT" command. 



SUcky points are points located on or near existing objects on the screen. 'Hicy are useful for connecting 
lines to 'Objects, specifying points actually on the object, etc. GROUre themselves do not have stici<y points, 
although Uie objects within a group may. Curves have one sticky point per control point. 'ITiese points arc 
located midway between each pair of control points. When you request tliat the program select a sticky point, 
it will choose the nearest such point which is within a given radius (about I inch). If you are furtlier trying to 
specify a point on a spwiflc type of object, the search for a suitable point is begun again from die previous 
result Naturally, if the original mouse click relocated to a sticky point on an object of die pi oper type, diat 
will be tlic closest point for any further searches. 

Grid points are spaced every 16 pixels (at normal magnification). If you wish to vSee these grid points, use 
the 'I'ogtjle Grid command within tlic Vgtscxec. I'br printed output, pixels arc assumed to be distributed at 
100 per inch. 

The Almost Done command is quite similar to Uic Done command described below, in that it tells the 
program you are satisfied with tlic selections you have made, and Uiat you wish the program lo accept ihem. 
Unlike the Done command, it does not tell tlie program diat you arc completely finished with whatever you 
were doing. Instead, it permits you to, for example, erase several objects of the same type without having to 
go to the Menu each dmc and specify the hlrasc command and Uic object type. 

it differs from a "repeat" command In diat it docs not force the program to create a checkpoint before 
beginning Uie next command. As a special case, when in conjunction with the Draw comm(md. Almost Done 
and Abort behave slightly dilTcrently. Abort will cause Uie last item you drew to be rcnn)ved, and Undo will 
subsequently remove all.of Uie others. NoriTiaily, Abort would cause ail changes since the command began to 
be removed. 

1'his command is also quite useful when drawing a scries of objects of similar type. You can specify Uiat 
you wish to draw a closed curve, place die control points for die curve, and Uien confirm with die right two 
mouse keys (Almost Done). The program will complete die curve you have outlined, and wait for you to 
specify another closed curve, just as if you had confirmed witli Done, and then selected Draw Closed 
Curve again. 
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8.6. Selecting Objects 

The standard-method of selecting an object is to first choose the object type and then to point at the desired 
object on die screen, using some combination of mouse buttons which specify a data point. If you select the 
wrong object type, simply point at and choose a different object type before you select the object itself. As a 
short cut, Uie program maintains a notion of what it considers to be the "Current Object", i'his will be die 
last object you selected. If you choose the object type CURRiiNT ORjnCT, and it is unambiguous as to what the 
current object is, this will suffice. After you select an object, tliat object will be "highlighted" on die screen. 
This normally consists of frame or bounding box appearing around the object. If the program misinterprets 
your pointing, use the Undo command (also available by pressing the right two buttons on die mouse) and 
then point to a different location on Uic screen. 

The most notable exception to this process is die mediod Ibr selecting groups. Since individual objects can 
appear in several groups, a popup menu appears when you select the GROUP object type, listing all of die 
existing groups. Hither choose one of these groups from the menu, or click outside the menu to abort 



8.7. Action Commands 

'Hicre arc nine action commands. Fach is useful for manipulating one or more objects. Typically, each 
action command will require die selection of an object type. 

Rotate This command will permit you to select an object, specify a fixed point about which die 

rotation is to tiike place, and two points which will defmc die angle of rotation. 

Text is rotated about its positioning point Only the position of die text is changed - die 
orientation of individual letters is constant 

Scale 'ITiis command will permit you to select an object specify a fixed point for the scaling, and 

two points which define the scaling vector. Iliis commarid is useful for expanding and 
contracting objects. > 

Scaling text will not change its si/.c or font It will change die location of die string based 
upon ils positioning point 

(Wove 'Hiis command will permit you to select an object and dicn specify a pair of points which 

define a displacement vector. This vector tells die program how far and in which direction 
to move die object By using diis command, you can move existing object about on die 
screen. 

Copy This command is similar to Move, except diat it leaves behind an image of die object If 

you copy anything otlicr Uian a group, die two resulting items arc completely independent 
Changing one will not affect the other. Groups, on die other hand, work differently . 
When you copy a group, it simply creates a new image of die same group, appending '* , 
copy n" to die old group name, where n is a small number. 

Draw This command lets you create new objects. Since it is anticipated that most of die time 

spent in diis program will be drawing new objects, this is (so to speak) the default 
command. If you ever select an object type without giving a command firet die program 
will assume diac you implicitly meant to draw an object of diat type. 

Alter lliis command is useful for changing die characteristics of an existing object It will permit 

you to move die control points on splines, change die filling and nib selections used to 
draw objects, etc. Currently Unimplemented. 

Erase Tliis command allows you to delete (erase) objects from die screen. If you decide you just 

don't want to sec an object any more, erase it. If you decide that the last command you did 
was a mistake, you probably want to use the Undo command. 
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Push to Back Also known as Lower, this command will place die selected object behind all of die other 
objects. This is usefiil when you use opaque ink to fill something, and it winds up 
obscuring an object you want to see. 

Bring to Front Also known as Raise, this command functions, much like tlic one above, except that it will 
place the selected object on top of all of the other objects. Note that you can ^till point to 
objects you can't see - die program will find sticky points on completely obscured objects 
with no difficulty. 



8,8. Object Types 



There are nine selections widiin die Object type menu. Some of the selections are obvious, some are not. 
All aro meaningful for selecting existing objects, but die "Draw All Objects" command is not. 



All Objects 



Text 



Olicn Curve 



Closed Curve 



Current Object 

Open Polygon 
Closed Polygon 
Group 



Template 



This will permit you to select all objects at once. If you decide, for example, to move 
everything on the page a bit to the left then this is die object type you want. The dear 
Scroen command (available under Mi3c) simply docs an "Knise A1 1 Objects", and 
then sets die dirty flag to false. 



As is obvious, diis will select any text string. It doesn't matter what font die text is in 
all of object type text. 



It is 



An open curve is a spline with open end conditions. When you create one, die fivst and last 
control point you specify will actually be on die curve, and die curve will be tangent to its 
convex R'ull at these points. (It gets straight at die ends.) 

Closed curves are splines with closed end conditions. To create one, you specify all of die 
control points you desire (the program will build a frame for die spline to iicip you 
visualize the resultant curve. You do not need to try to get die first and last control points 
in die same place - die program will close objects automatically. Closed curves can be 
filled. 

This will select die airrent object, if one exists. If you attempt to "Create Current 
Object", the program will interpret diis <is a request to create an object of Uie same type 
as die current object 

A bunch of connected stniiglit lines. (Internally, diesc arc Just splines of order 2, duis using 
linear interpolation.) 

Also straightforward. Closed polygons can be filled. 'Hie program will automatically add 
the last edge, dosing die polygon. 

Groups are a bit tricky. A group consists of several existing objects, lumped together and 
treated as a singled named object 1b create a group, you select as many existing items as 
you like, and they are all placed into die group. Once items are inside a group you cannot 
select them by normal means. 'Hicy arc in elTecl hidden inside the group. 

Groups arc useful if you have a complicated, complete figure which you wish to deal with 
as a whole. Due to internal limitation, you can't have more dian some fixed number of 
groups active at one time. 

Templates arc standard shapes. The broad classes of standard shapes arc arrowheads, 
circles, ovals, and rectangles. Arrowheads can cidicr be open or closed. Closed 
arrowheads are filled with black ink. 'Hie nib used to draw an arrowhead will be die same 
size as the die current nib, but will be circular. - , 



Rectangles and Ovals arc both created by specifying two points on a long diagonal of die 
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bounding box. You can give eitlicr tiic upper left and tlic lower right or the lower left and 
the upper right. Tlie program doesn't know tiic difference. 

Circles arc created by specifying the center of the circle and a point on the circle. Since 
circles are actually high order splines (5^*^ order, using quartic interpolation), they arc not 
truly circular. If you draw a really large circle, it is possible tliat the point you specify for 
being on the circle will be off by as much as a quarter of an inch or so. For normal sized 
circles, diere will be no difftcultics. 



8.9, Default-setting Commands 

There arc a number of Menu selections which control various defaults within the program. Tliey can be 
selected at any time. They are: 

Text When you select this command, a popup menu will appear. You can use this menu to 

specify either the method of positioning text, or the general class of font you wish to use. 

'Hiere are three different ways of positioning text - you can specify (with a data point 
entered via Uic mouse) cither the boiti)m left-hand corner of die bounding box for Uic text, 
the center of tlic bottom edge of die bounding box for the text, or the bottom right-hand 
corner of Uie bounding box. Initially, tlie program positions text based upon the ccjilcr of 
the bottom edge of die text You can only specify a point on die lower edge of die text 
- die program will aulomuticnily compute where die bounding box for the particular piece 
of text lies. If you are confused about where text should appear, try positioning a few 
strings, using die exact positioning (leftmost) mouse button. 

If you wish to change the font in which new text is displayed, choose one of the font menu 
selections. A second popup menu will appear, listing all of die available fonts. The 
"Stiindard h'onts" category contains die fonts which can be considered to be mundane text 
fonts " variations on Helvetica, Times Roman, and a few randoms like Clarity 12 and 
Cream 12. The "Unusual Konts" selection contains everything else - Old [English 18, 
Hebrew, Cyrillic, Greek, API., Math, CMR, etc. 'Hierc are some fonts, like Gates 32 and 
Template 64, which arc vci7 difllcult to use unless you are quite familiar with dicm. They 
are included primarily for completeness s<\ke. 

l''ill on/off ITiis tt)gglc controls whether or not closed »)bjects (Closed Arrowheads, Rectangles, Circles, 

Ovals, Closed Cui^ves, and Closed Polygons) arc lilled by default. If you wish to use 
created lilled objects, set diis switch to Kill on. Toggle die switch by pointing at it and 
clicking the mouse. 

Nib If you wish to change the nib (paint brush?) used to draw lines, select diis command. 

There are four nibs, each of which comes in four sizes. The program initially uses a 
Circular nib of size 1. The four nib shapes are Square, Circular, a horizontiU Dash, and a 
vertical IJiir. The four sizes are (unsurprisingly) 0, 1, 2, and 3. Size 0 is a single pixel, so all 
of die nibs look die s<imc at diaC size. An example of the current nib, at die current size, is 
displayed in diis area. 

Fill Hiis command allows you to change die fill pattern used to shade closed objects. A small 

square section of Uic current 1111 pattern appears in diis area. When you select Kill, a popup 
menu will appear, permitting you to eiUier toggle die use of opaque vs. translucent ink or 
select a general class of fdl pattern. 

The "Striping Patterns" consist mostly of lines drawn at various angles. The program ■ 
initially uses die one pattern least like straight lines but sdlt considered, a striping pattern: 
Chain Link« 
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The "Gray Tones/ Area Patterns" selection consists more of patterns wiiich are citiier 
various shades of gray, or arc regular and (to some) uninteresting. These patterns are 
useful for highlighting objects. 

The 'Textured Patterns" are supposed to be more representative of actual textures. The 
names for these patterns arc supposed to be suggestive of their appearance, but many of 
the names are nonetheless obscure. 



8.10. Permanent Menu Commands 

There are a few commands which are generally useftil, and arc thus considered permanent Not all are 
meaningful at all times, but arc still useful enough to be given an entry on the Menu. 

Exit This command will exit the program. It can be used at any time. If you have performed 

any command since either clearing the screen or writing a file, the program will ask you to 
confirm that you actually wish to exit even though there arc unsaved changes. Typing "y" 
will confirm. Typing anything else will abort the command. Note that since the program 
is reading input from the keyboard when asking you to confirm, any mouse clicks you 
make will simply be queued, and when you do type at Uie keyboard Uicy will all be dealt 
with. In particular, be careful about using the Abort command here. 

Help This command will provide a brief description of any other command you like. To get 

help on a specific command, just select Uiat command after you select help. To get help 
with the mouse buttons, push any one button in the drawing area. To exit help, select Help 
again. You can ask for help at any time. 

Misc 'ITiis command is actually a front for a collection of less frequently used commands. The 

various commands are for clearing the screen (only valid if no other command is in 
progress), reading and writing files, generating press files, and toggling debug printouts. 
The debug printouts are long and plentiful — tliey are also meaningless to Uic uninitiated. 

Reading a SUN draw file does not clear the screen ~ it adds the new objects to the current 
display. Press files currently unimplementetL 

Undo 'ITierc arc actually two forms of Uie Undo command. If you select it while at the top level 

(when there arc no other commands in progress), Uie elTect will be to rcvert to the previous 
checkpoint in cITect undoing the last command. The program maintiiins a list of 10 
checkpoints, so you can undo up Lo 10 commands. 

Checkpoints are copies of the complete stiite of the drawing area. The program will make 
one before it stiirts any action command. In this way, the Aiiort command doesn't need to 
keep ttxick of incremental changes duri ng the processing of a command. 

If you give the undo command while in the pnKCSs of specifying another command, it will 
attempt to undo your last choice. If you are specifying data points. Undo will delete tlie 
Inst point you entered. If you are selecting an object Undo will unselect the object and 
pemiiit you to choose again. 

Abort This command will abort any command in progress. In general. Abort will also revert to 

the last checkpoint since action commands all make a checkpoint before they begin 
processing. 

Done This command is used to tell the program that you are happy with all of your choices, and 

are done specifying parameters. After you hit Dono, tlic program will attempt to perform 
whatever command you are executing, and will display the results. Note tliat by pressing 
down tlic left two mouse buttons while in Uie drawing area, you can give Uie Almost 
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Done command, which will confimi all of you selections, but not stop the command. In 
this way you can. for example, create several objects at once. Note, however, that if you 
use the Almost Done command, you arc not guaranteed that a checkpoint will be made. 
If you create several objects with Almost Done, and then hit Abort, some (perhaps even 
all) of the new objects may be aborted also. 
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— 9 — 

bits: a bitmap and font editor 



bits is a spccial-pur];)ose editor for working witli bitmaps and fonts. It maiccs intensive use of tiie VGTS. 
TTic VGT of the executive under wliich bits is started up, is used to display various status information, as 
well as being the menu of commands to execute. When started, bits will asic for you to create a new view in 
which the actual editing is performed. If you request to view sample text, you will be asked to create a third 
VGT (see below). 'Hiesc last two VGTs can be zoomed. 



9.1. Command input 

In this chapter, when you are asked to do tlic command [xxx], it means that you should select and click 
tlic mouse at tlie field [xxx] of the status/command VGT. You get tlie same Iccdback as with pop-up 
menus, with the field in inverse video. Some of these fields, when activated, expect yt)ii to type in some 
number or String. In Uiose cases, you have tlic full power of the line editor, until you type a <return>. (To 
abort input, type CrilL-g.). 



9.2. Rasters 

ITie important thing to remember is thai bits handles pointers to biunaps. These we call rasters. A raster 
also contains size and olTsct data, so it can point to part of a bitmap. You can name a raster using the [Store 
with new name] command, and later retrieve it from the Table of saved rasters. You can thus 
save multiple pointers to the Siime bitmaps under different names. If you change bits in one of the bitmaps, 
the bits will also change in the other rasters, since they refer to the same biunaps. Use die [Save a fresh 
copy] command to make a vii-gin copy of a biunap, which is guaranteed to have no other fiusters pointing at 
it. 



9.3. Changing Raster Size 

To change the size of a raster, point at tlie boundary, click the mUhilc button and "move" the boimdary to 
where you want it. You can also change tlie si/c of a nuster with tlie [Width] and [Height] commands. To 
do this, select one of these fields, and type in a number. The absolute value typed in becomes the new si/c. If 
the value is positive, the old and new rasters coincide at the top Icil corner; if tlic value is negative, diey 
coincide at the bottom right comer. 

Note that when you change a raster's size, all other rasters pointing at the Siimc bitmap will be adjusted to 
point at whatever bits they used to point at. 'Hiis is true even when you increase Uic size. (When the size is 
increased, and the underlying bitmap is larger Uian the part pointed U) by the current raster, tlie hidden part 
of Uic bitmap will appear. If Uiis isn't enough, a new biunap will be allocated, and all the pointei'S adjusted.) 



9.4. Bitmap I/O 

You can read and write bitmaps in .sun format (as used by die photo program), using die [Read 
paster] and [Write raster] commands. To write a raw raster in hex suitable for putting in a C 
program, use die [Write hex] command. 
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9.5. Painting 

To set (blacken) a pixel, point at it with the mouse, and click the lefi button. To dear (whiten) a pixel in a 
bitmap, use the middle button. 



9.6. Inverting a Raster 

Selecting [Invert black and white] inverts the interpretation of black and white pixels. This 
interpretation is actually stored as part of the raster object, so no pixels are actually changed (except on the 
display). 



9.7. Raster Operations (BitBIt) 

You can do a general 2^operand BitBIt with the [Raster operation] command. The current 
(displayed) raster is used as one of the operands (tlie "destination"), so this should be selected first. Then give 
the [Raster operation] command, after which you will be asked to select an operation. Available are 
plain copy, 'and', 'or* (paint) and 'xor'. In addition, tJic [Invert Source] modifier first inverts Uic source. 
[Invert Destination] docs die same for die destination, which means inverting the destination 
operand andWK output result Finally, you must select tlie other operand (the "source") from the name table. 

You can also select [Get the empty raster] as a source. This gives you an infinite plane of white 
pixels. Hiis, together with the [Invert Source] option, allows you to conveniently clear or set any 
rectangle. 



9.8. Reflection and Rotation 

Selecting [Reflect/Rotate] will do one of tliese u^ansformations. (A popup menu asks for the 
particular transformation.) Note that tJie result is a "fresh" raster: There are no other raster or tables 
pointing at its biUnap. 

9.9. [Replace in table] 

'ITiis command ask.s you to select an clement in the raster Ciible or Uie current font. The clemciu is replaced 
by the current raster. If a [Table of saved raster] element is replaced by the limpty Raster, its space 
is freed. 



9.10. Making a Copy of the Screen 

You can make copy of the frame buffer, with a little bother. Select [Get f ramebuff er], which gets a 
pointer to the frame-bulTer. You should now use [Height] and [Width] to reduce Uie time and space 
required to deal with it. (The framcbuffcr is ^/g.) You should [Save a fresh copy] t(» see what's going 
on, and llicn use Uic middle button lo select tlic part Uiat interests you. This wilt be slow, since such a big 
raster is involved, and you will also have to use the Vgls window manager commands. 



9.1 1. Fonts 

A fotu is a collection of characters. From bits' perspective, a character is a bitmap with some extra 
information, bits currently knows about fonts in tlie following fomiats: 

• sf format ("Sun format"), which is specially optimized for llie Sun graphics hardware. (The name 
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should probably be changed, since it conflicts with Xerox' Spline Format.) 

• The same format, but the font is stored in an archive (library) of relocatable binary files. Thus fonts can 
be linked in with programs, or read in at run time. The standard fonts are stored in 
/usr/sun/lib/libsfsonts.a. 

• Pxl format, which can be generated by Mctai'ont, and is used by a lot of the TeX people. 

To read / write a font select the desired field in the Read font | Write font table. Note that you 
cannot write a font to an archive. 

9.11.1. Displaying Fonts 

When a character in a font is displayed, there arc funny lines sticking out of the biunap picture. Tlie two 
horizontal lines show where the baseline of the character is. The lower vertical line shows tlie starting position 
("origin") of the chanictcr. The top line indicates tlie width of the character, and shows where die next 
charactei's should start You can select any of Uicsc lines (with the middle button), and adjust diem with the 
mouse. 

9.1 1 .2. Font parameters 

This is a section of tlie pad with magic numbers about the current font. They can all be changed, but you 
should know what you arc doing. 

Design size is tlie size in points at which the font is designed for. Magnification is one tliousand 
times die number of times die image is magificd, relative to a default Pxl resolution of 200 pixels/inch. To be 
compatible with die Altos, we have decided diat the resolution of die Sun display sht)uld be defined to be 80 
pixels/inch. This means diat die 1.0 magnification will have the magnification parameter of 400, which is 
somewhat small. Both dicsc are TeX/Px I parameters. 

[Raster al ignment] is die bit boundary character biunaps should be aligned on in sf font files. It 
must be 1, 8, or 16. 



9.12. Sample Texts 

To study how a text siring would look at no magnification, select [Sample text]. You should ihcn type 
in die icxt you want displayed. This text will be placed in a new VC3T. To change the icxt, just rcscicct 
[Sample text], die old text will be placed in die line editor bufler, to simplify small changes. If you edit 
the font, select [Redraw] to update die siimplc. 

Note diat in die Siimplc, die character ' \ • is special. It is used to indicate special non-ascii characters, as in 
C. Specifically, ' \ ' followed by a 3-digit cKtal number is die character with diat ordinal value. \\ displays \, 
and \b, \t, \e, \r and \n are Backspace, Horizontal Tab, I'lscape, Carridgc Returen and Line Feed, 
respectively. \9, \A, ... \_ are control characters: tQ, tA, ... t_. 



9.13. Printing a Raster 

There is a Unix program to convert a . sun file to a .press file. To run it (on some Stanford VAXcn). do: 
/usr/sun/src/graphics/pix/sunpress -p X. press X.sun 

This, Uigethcr with die [Get f ramebuf f er] command, allows you to print a hardcopy of die screen .on a 
[])over printer. 
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9.14. Bugs and Problems 

.sun files use 1 to mean 'white' while bits uses 0. This means that you should [Invert bl acic and 
white] after reading and before writing, if you want to use the bitmaps for programs like sunpress and 
photo. 

The are some limitations on how bitmaps are displayed by the VGTS. A biunap can only be should 
magnified I, 2, 4, 8, or 16 times, so other zoom factors will be wrong. Also, it is over-conservative when 
clipping rasters, which means that a whole row of bits could bo missing. 

Raster operations do not take into account that rasters may be overlapping. 

bits is not very robust against things like rimning out of memory. Caution would imply diat you save 
your work often. 
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Amaze 



Amaze is a game for t^vo to five players which runs under the plain (non-VGTS) exec (VV). If you sec the 
letters VGTS in a small window on your screen you are not running the plain exec. See section 2.2 for 
instructions on how to start up the plain exec. 

To run amaze, type the command 
amazo 

If no one else is playing, it will type "New game starting" and then draw the maze. Otherwise it responds 
with "Joining game as player number x" and then draws the maze. Your player token, called a monster, will 
be sitting in die center of the screen just above a checkered flashing door. From tliis point, you control your 
monster through die keyboard. 'Hie commands are: 



1 Move the monster up. 

, Move the monster down. 

j Move the monster left. 

1 Move the monster right. 

k Hold the monster at its current position. 

a Let the monster's moves be selected randomly. 

e Fire the monster's missile up. 

c Fire the monster's missile down, 

s Fire the monster's missile left, 

f Fire the monster's missile right. 

(Note: the missile can be fired only once every six 
seconds.) 

h Hide the monster from other players — no shooting allowed 

while hidden. 

V Let the monster be seen again — can shoot again, too. 

(Note: monsters stay hidden for ten seconds, but once 

they become visible, they remain visible for 16 seconds.) 

0 Set monster velocity to 0. 

1 Set monster, velocity to 1. 

2 Set monster velocity to 2. 

3 Set monster velocity to 3 — the starting velocity. 

4 Set monster velocity to 4. 
6 Set monster velocity to 5. 

q Quit the game, but continue to watch other players, 

t Rejoin the game just above the door, 

r Rejoin the game at a random corner in the maze. 



Ctrl-C Terminate your involvement with the game. 

Note that to leave the game cndrciy you hold down tlic Cl'RL key and type 'c'. 
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To rejoin the game after being shot by another monster, use cither the t or the r command. The game 
currently docs not keep score of tlie number of hits you inflict or suffer. 

Problems and questions should be directed to Eric Berglund - bcrglund@Diablo. 

checkers aWom you to play a game of checkers against the computer. This version of the program executes 
entirely on the player's workstation. 

On starting the program, the view manager will prompt you for the position of the VGT representing the 
checkerboard. 

The player moves the 'red' (white) pieces; the program's pieces arc black. You arc expected to make the 
first move. You can, however, force the program to move first by "passing". (Sec the paragraph describing die 
menu, to follow.) 'I'o make a move, move the mouse to tlie square conuiining the piece that you wish to move, 
and click cidicr the left or Uic middle mouse button. If tliis piece can be legally moved, it will then be 
highlighted. Complete die move by moving tlic mouse to the dcsdnation square and once again clicking die 
left or the middle button. 

If the move iliat you have selected is legal, your piece will be moved, and the program will tlicti make its 
move. Note tlwl having selected a piece to move, you can abort tliis selection by clicking an illegal destination 
square (the source square itself, for example), (fa ciipturc of an opposing (ie. black) piece is possible, your 
next move must be a capture. A messiigc indicating such "forced captures" will be displayed just below tlie 
board. In such a case, the program will not allow you to make a move Uiat is not a capture. IVIultipIc captures 
arc handled correctly - if you move a piece by making a capture, your move will not be completed unUl all 
possible captures with this piece have been made. 

Tlie standard ailes of checkers apply. If a piece rcxichcs the eighth rank of the board, it is promoted to a 
king: kings may move in any direction. A side wins either by capturing all of the opposing pieces, or if die 
opposing side can make no legal move. 

When it is your turn to move, you may also use die right mouse button to select from a menu of options, 
which arc described below: 

Redraw This causes U\c VGTS to redraw the endrc board. This command should rarely be 

necessary. 

Pass (skip turn) This command can be used if you want tlie program to make the firet move. You can also 
use diis to avoid any capturing obligaUons. 

Change search depth 

iJy default, die program searches 4 half-moves ahead when choosing its next move. That is, 
it considers its own move, your response to this move, its next move, and your response to 
diaL The "Change search depth" command alU)ws you to change tlic depth of lookahead 
to any value from 1 to 8. Don't select any of tlic higher depdis unless you have a lot of 
patience, however. The program takes about 20s to respond to a typical opening move 
when the depth is 6, about 50s when tlie depdi is 7, and about 3 minutes when the depth is 
8. (These limes were taken on a 10 MM/. SMI workstiUion - Cadlincs will be slightly 
slower.) Note that you may find out iJic current search dcpdi by selecting "Change search 
depth", and. then clicking outside Uic 'depth' menu. 

Edit board This command puts you into Kdit mode, which allows you to cheat by adding pieces to, or 
removing pieces, from, die board. Udit mode is described below. 

Back up one move This allows you to retract (eg. to ct)rrect) your last move. 

Resign The quick and cowardly way to end the game. 

Tlie program chooses it's move by performing a. 'brute-force' search, using alpha-beta pruning. It evaluates 
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the board positions at tiic 'leavqs* of the search tree using a simple heuristic based on tlic number and position 
of pieces on each side. A 'value indicator' to the right of tiie board indicates the value of the current position, 
as seen by the program. (If the indicator is above Uie halfway mark, for example, then the program 'thinks' 
that you are winning.) There are also counters immediately above and below the value indicator, giving the 
number of pieces on each side. The value indicator and tlic piece counters are updated whenever the program 
completes its move. 

You can make changes to the board (between moves) in Edit mode. In this mode, a special menu is 
displayed to the right of tlie board. To add a piece to die board (or change an existing piece), click the square 
in the menu that contains that piece. You may place a copy of this piece on any (shaded) square of the board, 
by clicking that square. You may do this repeatedly; it is not necessary to select from the menu each time. 
Note tliat you use the 'empty square' to delete one or more pieces from the board. You may remove all pieces 
from tile board by clicking "Clear". When you have finished making changes to the board, click "Done" to 
leave Kdit mode. It will still be your turn to move next 

Mail comments and/or gripes to Ross Finlayson - rsf@diablo. 
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Fscheck: File System Checking Program 



This program is a file system disk checker as well as simple file system editor that can be used to inspect and 
modify file system disk data stRicturcs. In addition, it gives one the capability to create and initiali/c new file 
systems. Fshcck must only be used when dicre is no otiicr file system activity. It also should only be used by 
persons responsible for maintaining the file system. 



11.1. Invocation 

One can invoke fscheck from within the V system executive by typing 
fscheck 

or 

fscheck devicename 

If no device name is specified, fscheck attempts to open two devices, [device]diskO and [device]diskl. Non- 
existence of a second device does not affect correct operation of the program. Note that the devices must be 
attached to the workstation firom which the command is invoked and the kernel amning on die workstation 
must include the proper disk driver (sec the Kernel Section for details on which kernel should be booted). 



1 1 .2. Commands 

Commands are provided to clieck tlic global data stmcturc consistency of each file system, inspect and 
modify individual node descriptors (ND), and initialize new file systems. 

a(+r] [4-sj check the consistency of the file system bk)ck allocation. If +r is specified, the bitmap is 
rcconstitictcd. If +s is specified, error mcssiigcs about blocks marked in the bitmap but 
not allocated to a file are suppressed. 

b block print the nd number of all node descriptors tliat point to the given bUx:k number. 

Noimally, there is at most one. If the allocation is inconsistent, a block may be allocated 
more than once. 

c update the checksum in the current ND, print it, and set the current field to the checksum 

field. 

f print the pathname of die current ND relative to die file system being checked. 

g field set die field corresponding t6 die given name as tlic current field and print die current 

field. 

i initialize file system information. Prompts die user for the name, drive number, stari 

block, and length of each file system in die disk subsystem and writes die information intc 
die file "fstob" on die root file system. Note that die suirt block of the first (root) file 
system should correspond to die S'rART^FD.FlLH definition (usually 40) in 
"/V/servcrs/storage/storagcdcfs.h". Warning: diis command should only be executec 
when new file systems are being created. 
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print all links from and to the current ND. 



Q<path>|<nd> set the ND corresponding to die given pathname or number to be die current ND. 

Pathnames must be specified as absolute padinames (i.e. starting with "/"). If a padiname 
cannot be followed, the current ND is set to the last node visited while looking up die 
pathname. This occurs if die node does not exist or die padi from die root cahnot be 
followed (e.g. a node in die padi has a bad checksum). 

p print all die fields of die current ND. 

q quit 

s number set the current file system to be the one indicated by number, 

t check die consistency of die file system tree structure. 

w write die current ND back to disk. The ND number is taken from die current value of die 

number field. If die current ND describes an allocated node (i.e. its name field is not die 
null string), it is written only if Its checksum is correct If it describes an unalkx:ated node, 
■ it is written uncondidoiuilly. Checks that die number field is correct before writing die 
current ND out. 

<RHTU11N> advance to the next field and print its name and value. Hitting <RErURN> after an "n" 
command prints die first field. 

print die current field. 

t set die current field to the previous field and print it. 

= <number> | <str> 

store die given number or string in die cuiTcnt field and print it. The number may be 
decimal, octaK'O' prefix), or hexadccimalCS' prefix). A string is a sequence of characters 
and must be enclosed by double quotes. A null string is represented by Strings are 
accepted only when tiic name field is being modified. Note diat modifications are not 
effecUve undl a "w" command is issued. 



11.3. Initializing a new disk subsystem 

Once die disk drive(s) have been fi)rmatted (using diskJiog), die characteristics of each of die multiple 
possible file systems siiould be specified. This can be accomplished by creating die root file system (as 
described below) and subsequently mnning die "i" command. Then, using the "s" command to successively 
switch to each new file system, die rest of Uic file systems should be created. 

11 .3. 1 . Creating a new file system 

To build a new file system, one should allocate blocks to the ND file (ND 1) and to ihe bitmap file (ND 2). 
(If the file system being created is die root file system dien a single bUx:k should be alUx:ated to "fsuib" (ND 
3).) This is done by modifying diesc node descriptors so that each refers to non-overlapping extents of disk 
blocks. Also, die link fields in each node descriptor should be updated so diat a proper tree stmcture exists, 
i.e. ND 2 is die son of ND I and ND 3 is tlic brodicr of ND 2.'* After diis is done, a "t" command should be 
used to check tiie consistency of die new tree structure, and an "a + r" command must be issued so diat die 
bitmap reflects diesc newly allocated blocks. 



In the ticar fulurc, ihc task of creating a new file syslcin will be automated. 
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1 1 .4. Checking file system integrity 

Once the "s" command has been used to set the current file system to the one you want to check, test the 
consistency of block allocation using the "a" command. Used with the +r option, it rebuilds the bitmap file 
in the case of missing blocks (i.e. blocks marked as allocated in the bitmap but not actually allocated to any 
file) or blocks alkx:ated to a file, but marked as free in die bitmap. Blocks allocated more than once have to 
be handled manually. In this case, use the "b" command to determine to which ND's they are allocated. Use 
the "n" and the 'T commands to determine the pathnames of tliosc ND's. Make copies of the conflicting 
files and remove the old ones. Note that the information in the files may be damaged. 

Second, check the tree structure using the "t" command. If there are missing links, find out what they 
should be using "n" and "1". If diere arc nodes completely disconnected from the file system, remove diem or 
else determine from their father pointers where they should be in the tree stnicture. The easiest way to 
remove a disconnected node is to mark the corresponding ND as unallocated (setting the name field to the 
null string) and Uien using "a + r" to recover the blocks that were allocated to diat file. 
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Standalone Commands 



This chapter discusses standalone programs, i.e.» programs that do not run under the V kernel, tiiat are 
useful with the V-Systcm. 



12.1. VIoad 

Vhad is the V-System bootstrap loader. The Vload program loads the V kernel and initial team Into 
memory and starts up the kernel. 

There are several versions of Vload. Currently, all versions use the V I/O protocol and V IKC protocol to 
load programs over tlic Htlicrnct.^ On the Sun-1, die Sun 3 Mbit Htliernct board and lixcclan 10 Mbit 
Ethernet boards are supported as boot devices. On the Sun- 1.5 and Sun-2, the 3Com 10 Mbit Hdiernet board 
is supported. 

Vload determines die files to load and other actions to take at run time, depending on what was typed on 
the command line and what information is stored in the conflguration database i'or die workstation being 
booted (sec section WORKSTATIONCONPIG). For each of its parameters, Vload gives first priority to 
command-line information, if any, second priority to the defaults for this workstation recorded in die 
configuration datiibasc, if any, and diird priority to a default value determined at compile lime. 

Team and kernel filenames are interpreted in the V-Systcm '^[public]" context, unics;^ tlicy begin with a 
square braciceL In Uic latter case, the name inside brackets is taken as a machine name, in the same name 
space used by tiie /«gm command. If is given as die kernel file name, no kernel is loaded. Instead, die 
file specified as first team is loaded into die kerners memory area and executed as a standaK)ne program. 

Besides file names, two other parameters are also required: "world" and "options," Tiie world may be 
either V (production) or xV (experimental). The only option currcnUy recognized is *b\ which causes a break 
to die PROM monitor before Uie kernel is stin ted. 

'I1ic following sections describe Uic defaults and special characteristics of die diree versions of Vload in use 
at Uiis writing. 

12.1.1. 3 MbltEthemet 

This version of Vload is intended for booting Cadlinc, SMI Sun-1, and other Sun-1 workstation 
configurations with 3 Mbit Sun HUiernct boards. These workstiitions ordinarily use a vcreion of die SUinft)rd 
PROM monitor Uiat incorporates PUP biwtstrap code. The fii-st step in booting Uiese workstations is U) load 
Vload using die b(M)(strap PUOMs. 'Iliis can be done by typing a keyboard cotnmand (b f Hename for SMI 
workstittions, n f ilanamQ for odiers), or automatically on powcnip or reset (sec below). 

For diese workstations, die kernel resides from 0x1000 to 0x10000, and teams are loaded at Ox 10000. 

The compiled-in default values for Vload's parameters in this version arc as follows: 

world Vtcam 



In ihc near future, ihcre will be a version o( Vload ihat can boot a nicscrvcr machine directly from its local dusk. 
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tcaml-vgts kernel 
Vkemcl/sunl+cn options 
null 

The only command line information visible to Vload is the name it was invoked under. Therefore, Vload is 
installed under several different names, and its action depends on its name. The names and actions arc listed 
below. 

V When called under this name, Vload will load the team teaml-vgts and the default kernel 

for this workstation, using the default options. The team and kernel are loaded from a V 
storage server (production versions) rather tlian an xV storage server (experimental 
versions), that is, the world parameter is set to V. 

VV The team is teamhsts, and the world is V. 

xV The team is teaml-vgfs, and the world \sxV. 

xVV The team Is teamhsts, and the world is jcK 

Vload 'ITjc user is prompted for team, kernel, and options. 'ITic default value is used for any field 

where the user enters a blank line, 'ITic world is V. 

xVload Same as Vload, except tliat the world is set to xV, 

null If the name is null, Vload assumes it was autobooted. Default values are used fur all 

parameters. 

others If a copy of Vload is installed under any odicr name, it will use its name as the team name 

to be loaded, set the options to null, and use defaults for tlie kernel and world. 

No special setup is required to get an SMI processor to autob(xit— it will do so automatically 30 seconds 
after powcriip or a k2 command. The PUP boot prom requests boot file number 1 by number, which causes 
a file called l.Boot to be loaded from the first responding PUP RFI P server. We have arranged for this file to 
be a copy of Vload, so the boot action is as described under tlie null name above. 

A non-SMI processor can be made to autoboot by installitig die proper jumpers in its configuration register. 
(See the Sun User's Guide for a full description of the configuration register.) BiLs 7-4 of tlic conllguriition 
register nre an index into a tiiblc ofbootfile names stored in the prom. An in-plnce jumper or closed DIP 
switch corresponds to a 0 bit; no jumper or an open switch corresponds to a I. These bits should be set to the 
number corresponding to the name "Vload." The "W W command typed to tlie prom monitor causes it to 
list tlie bootfile names and corresponding numbers that it knows about. Vload is usually number 5, 
corresponding to jumpers on bits 5 and 7. Vload's action will be as described under the null name above. 

12.1 .2. Exceian Ethernet 

'Hiis version of Vload is intended for booting Cadlinc, SMI Sun-1, and other Sun-1 workstatii)n 
configurations with Hxcelan 10 Mbit lUhernct boards. Ordinarily, this version of Vload is used only with 
workstations using a special version of the pkom monitor lhal incorporates TKI'P bootstrap code. The firet 
step in booting Uiese workst;uions is to load Vload using tlie bootstrap pkoms. This can be done by typing a 
keyboard command, not described here. 

The compiled-in default values for Vload's parameters in this version are as follows: 

world V team 

tcaml-vgts kernel 
Vkernel/sunl-f-ex options 
null 
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ThQ only command line information visible to Vload is tlic name it was invoked under. Therefore, Vload is 
installed under several different names, and its action depends on its name. The names and actions are listed 
below. 



xlnV 



xInVV 
xlnxV 
xlnxW 
xln Vload 

xlnx Vload 
others 



When called under this name, Vload will load the team icarnl-vgts and the default kernel 
for this workstation, using the default options. The team and kernel are loaded from a V 
storage server (production versions) rather than an xV storage server (experimental 
versions), that is, the wor/c/ parameter is set to V. 

The team is teaml-sts, and tlic world is V. 

The team is team I- vgis, and the world is xV. 

The team is team I -sis, and the world isxV. 

The user is prompted for teanu kernel, and options. The default value is used for any field 
where the user enters a blank line. ITic world is V. 

Same as Vload, except that the world is set to jcK. 

If a copy of Vload is installed under any other name, it will use its name as the team name 
to be loaded, set the options to null, and use defaults for the kernel and world. 



There is currently no way to autob(M)t a workstation witli TFTP boot HllOMs. This limitation will be 
removed in the future. 



1 2.1 .3. 3Com Ethernet 

This version of Vload is intended for booting Sun-l.5s and Sun-2s with 3Com 10 Mbit Ethernet boards, 
lliese workstations boot using cither a k)cal disk or tape, or the SMI network disk prottxiol. The network disk 
protocol docs not allow specifying a file name, so the V-Systcm ND boot ser\'cr is only capable of loading one 
file— Vload. Vload, however, can read tlic entire command line typed by the user. 

The compiled-in default values for Vload's parameters in this version are as follows: 

world V team 

teaml-ygts kernel 
Vkerncl/sunl.5+ec options 
null 

Zero or more arguments may be passed on the command line to Vload. If die first argument to Vload is 
one of the special values described below, it is stripped off and die special action listed is uikcn. After this 
check, the first Uirec remaining arguments are respectively used to override die defaults for team name, kernel 
name, and options. Values set by these arguments have priority over values tliat may have been set by die 
first argument 

V Sets the world to V, and tlic team to teaml-vsts. (This team name will be overridden by 

the next argument if present) 



VV 

xV 

xVV 

null 

vmunix 



The team is set to team I -sis, and the world is V. 

The team is set to ieaml-vgis, and Uic world is jtK 

The team is set to teaml-sts, and the world is xV, 

If no arguments arc present the default values arc used for all parameters. 

The SMI boot PROMs have Uiis name hardwired in for autoboodng, so it is treated die 
same as a null first argument 
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Others If tlic fu-st argument is not one of these values, the default world is used, and the arguments 

present specify team name, kernel name, and options, as described above. 



12.2. Postmortem 

Postmortem M intended to provide some help in diagnosing system deadlocks, kernel aborts, and other 
disastrous errors. Any time the system seems to be hanging, you can break to the prom monitor, and type the 
command 

n postmortem 
Substitute b for n on SMI workstations. 

Postmortem examines die kernel data structures left behind after a crash, and prints out the state of each 
process, if any exist, the pid of the currently active process, and the ready queue. 

It is important not to use the monitor kl or k2 command or press the workstation reset button before 
running postmortem. 'ITicsc actions cause memory to be cleared. TTie prom monitor on a Cadlinc 
workstation will not operate properly if Uic mouse is active, but fortunately^ it is possible to turn off the mouse 
without power cycling Uic workstation by unplugging the keyboard and plugging it back in. ITiis should not 
be necessary if you were able to press the comma key on the numeric keyboard while die kernel was sdll 
running. 



12.3. Ipwatch 

'ITie ipwatch family of programs provide a way of monitoring die Ediemet to debug protocol 
implementations or search for the cause of strange behavior. Ipwatch knows about most common types of 
packets seen on die Stiinford network, including most PUP protocols, Internet protocols such as IP, TCP. and 
ICMP, XNS protocols, and die V interkernel protix:ol. It can print packet U^accs on die screen, or save Uicm 
in a file. pMwatch is a version for tlie Sun 3 Mbit Bdiemct board, while ecwatch works on the 3Com 10 Mbit 
board. Kxwatch works with the Hxceian 10 Mbit board. 

To nm enwatch, reset the workstation completely, and type die command 
n enwatch 
for Cadlinc workstations, or 
b enwatch 

for SMI workstations. The program is menu driven, and most options are self-explanatory. 

Currently, all versions of ipwatch use die PUP Leaf protocol on die 3 Mbit EUicmet to write packet traces to 
flics, and dicy run only on die Sun-1 with Stanford PRO Ms. 



12.4. Diskdiag 

Hie diskdiag program is a diagnostic pn)gram diat allows one to manually access specific sectors on Uic 
disk. It is useful for verifying the correct interaction between die disk controller and disk drives, as well as for 
initiali/.ing a new disk. Diskdiag is configured to run on a system with a Xyiogics 450 or Interphase 2181 disk 
controller and Fujitsu M2351 and M2284 disk drives. 

To run diskdiag, type die command 
b ec() diskdiag »^ 



Some SMI workstations with older PROM rcvusioas require thai nd() be used in place of cc(). 
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for SMI workstations, or 
n diskdiag 

for Cadlinc workstations. There arc commands available to fopniat(f), pead(r), se«k(s), and 
wr 1 te ( w ) . ITic user is prompted, as necessary, for more in formation on cacii of ttiese commands. 

In addition, it is possible to 1 ab«l ( 1 ) a drive with die configuration parameters needed by the disk driver 
in the kernel. Executing the format command automatically labels the disk after the format is complete. The 
va n i f y ( V ) command reads die label off of disk and prints it on the console. 

The parti t1on(p) command prompts the user for the start block and length of each partition on the 
disk and creates a disk partition table. Existence of a disk partidon table is optional as it is not needed by any 
system software. The examl ne ( x ) command allows one to examine the contents of the disk partition table. 

Reinitializing the diskdiag program is accomplished using theagaln(a) command. 



1 2.5. Offload and Offload38 

The offload program uses PUP RFTP to load standalone programs into a Sun-1 equipped witli a Sun 3 Mbit 
Ethernet interface, at a user-specified memory location. This program is useflil on Sun-l workstations 
equipped with standiu*d Stanford PUP boot PROMs, because they are only capable of loading programs that 
reside at the default address of Ox 1000. 

To use offioad, first reset die workstation, then give the command 
n offload 

to the .Sun prom monitor. (Substitute *b' for 'n' on SMI workstadons.) The program will prompt for 

1. The name of the program to be loaded. Tlic default directory is the miscserver's standard default 
directory, as described under Vload. 

2. llic load'origin of tlie program, in hex. This should be the same value specified to cc68 or ld68 with the 
-T option when tlie program was linked. Offioad will refuse to load a program diat would overlap part 
of the memory it uses; use oflloadSS if Uiis is a problem (sec below). 

3. Where to put a copy of tJic program's b.out header. 'ITiis is usually not needed; enter '0' to omit it. 

4. Whether to load Uic program's symbol table into memory. This is generally not needed. See the S'un 
User's Guide for a description of how program symbol Libles appear in memory. 

5. Whether to jump to the program's entry point or return to tlie prom monitor after tlie program is 
loaded. After returning to the monitor, the command 

g 1000 

will restart offload to load another file. 

Offload itself resides at 0x1000 so that it can be loaded by Uie PROM monitor. If it is necessary to load a 
program dial would overlap oiHoad's del'aull location, use ollload to load oJJloadSH at 0x38000. I'his program 
Is identical to oflload except for its starting address. 'VhQ command 

g 38000 

will restart ofFloadSS after a return to die monitor. 

I1ie following dialog can be used to load a nonstandard kernel diat is too large for Vload. User input is 
underlined. 
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STANDALONE COMMANDS 



> n offload 

Sun Offset Loader - Version 2.2 - 2 Feb 1983 
Loader resides from 1000 to 60e8 
Program to load: off 1oad38 
Origin (hex): 38000 

Place b.out header at (hex; 0 1f not needed): Q, 
Load symbols? (y/n): ji 
Execute? (y/n): x 

Sun Offset Loader - Version 2.2-2 Feb 1983 
Loader resides from 38000 to 3e0e8 
Program to load: /usr/sun/Vboot/teaml-sta 
Origin (hex): lOQQQ 

Place b.out header at (hex; 0 if not needed): ff aO 
Load symbols? (y/n): jq, . 
Execute? (y/n): n 

>q 3909Q 

Sun Offset Loader - Version 2.2-2 Feb 1983 
Loader resides from 38000 to 3e0ed 
Program to load: vour nonstandard kernel 
Origin (hex): 1000 

Place b.out header at (hex; 0 1f not needed): ff cO 
Load symbols? (y/n): n 
Execute? (y/n): yi 

Using "Aisr/sun/Vboot/tcaml-sts" as above loads the standard version of the plain exec. You can 
substitute tcnml-vgts or your own special fli'st team. 
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Part II: 
Program Environment 
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Program Environment Overview 



This manual, the V-System Program Environment Manual describes the execution environment provided 
for C programs written to run in the V system (and in particular the V kernel), primarily for programs in tlie 
C language. This program environment is designed to minimize the difficulty of porting C programs (and C 
programmers) from other C program environments, such as that provided by UNIX^, and to provide access to 
the distributed process and message facilities provided by the V kernel and V servers. 

The program environment consists of three major components: 

• The base C language implemented by the compiler. 

• Routines that are part of die C program library in most C implementations. 

• Functions that access V facilities. 

The basic C language is not described here. The reader is referred to The C Programming Language by B. W. 
Kemighan and D. M. Ritchie, Prentice- Hall 1978 for a tutorial on the language and stiindard C library 
routines. 

Standard C library routines are only described here to tlie degree they differ in the V program environment 
from other implementations, particularly die Unix C library. The reader is referred to tlie above-cited book 
or The Unix Programmer's Manual for details on these standard functions. 

The V-specific functions are described in detail in the following chapters. 

While there has been a strong attempt to provide a superset of the standard C program environment, there 
is no real definition of "the standard C program environment." While C as a programming language does not 
define 1/0 facilities, memory management, etc., an ill-defined de facto standard has arisen from the extensive 
use of C with the Unix operating system. Attempts to port C programs have resulted in a slightly more 
portable standard program environment tlian originally used with Unix. However, there is not, to die 
auUiors' knowledge, a definition of what a portable C program can reasonably expect of its program 
environment. The functions included in llie V pa)gram environment for C, excluding V and SUN 
workstation specific routines, constitute our proposiil for such a standard portable C program environment. 

The differences between the V C program environment and tlic Unix C program environment fall into four 
major categories 

• Functions that arc Unix system calls which may be provided as V library routines, c.g., stime(). 

• Functions that arc slightly changed in tiicir implemcntadon, but provide (essentially) the same 
functionality, eg., mallocO. 

• Functions that are SUN workstation-specific, because they are not necessary in standard Unix on, say, a 
VAX*. For example, die long division routines are in Uiis category, as are the emulator traps, 

• Functions that arc particular to the V-System, like CreateQ and Ready(). 



UNIX is a iradumark of Ikll Uboratoiics. 

'vAX is a iradcniark of Digital Equipment Corporation. 



V-SYSni'M 5.0 RFJ-I^RIiNCE MANUAL 



PROGRAM I'NVIRONMENT 



72 



PROGRAM ENVIRONMENT OVERVIHW 



13.1 . Groups of Functions 

The description of functions is structuricd-by subdividing tiicm according to functional groups as follows. 



emt 


C language interface to the on-board PROM monitor emulator traps. See the Sun User's 




Guide for more information. 


exec 


V-System program execution functions. 


fields 


Functions that enable a pad to be used as a menu, similar to a data entry terminal. 


io 


Input/output related routines. 


math 


Mathematical functions. 


mem 


Mcmoi7 management and allocation routines. 


naming 


V-System name management functions. 


numeric 


Arithmetic and numeric flinctions. 


process 


y-System process service functions and V kernel traps. 


strings 


Character string manipulation routines. 


time 


Clock and time conversion services. 


vgts 


Virtual Graphics Terminal Service interface routines. 


others 


Miscellaneous other functions. 


ITiis functional subdivision is also reflected in the structure of the program source for tlic V C library, where 


every subdivision corresponds to a subdirectory of die C library directory. 


13.2. Header Files 


The following header files define manifest constants, type definitions and structs used as part of the V C 


program cnviri)nmcnt. They arc included as usual by a "# include <headcrname>" directive in C programs. 


Vcnviron.h 


Standard header file Tor V kernel types and request/reply codes. 


Vethemcth 


Ethernet-specific header infonnation. 'ITiis is very low-level information; most users will 




want to use tlic network server instead. 


Vexccptions.h 


Exception types and exception request format 


Vgts.h 


Virtual graphics terminal server interface. This should be included in any programs that 




do graphics. 


Vich 


1/0 Prot(Koi header file. Types and mode consumts for file manipulation fijnctions 




described in chapter of tiiis manual.' 


Ymousc.h 


Mouse device-specific header information. Most programs will use the Vgts to handle 




graphics input. 


VneLh 


Network server definitions. This is included in any programs that use tlie network. 


Vprocess.h 


Processor state stRicturc and other process-specific header information. 


VseriaLh 


Manifests for die serial lines. Again, very low level for most users; use the higher level 




library interface instead to be more portable. 
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Vscssion.h Manifests and message stmcts for session services. These are remote servers, often called 
Unix or V servers, that provide transparent file access over a network. 

Vtcams.h Team, header file. Stmcturcs used to communicate with the team server and to pass 

infonnation to teams when they are created. 

Vtime.h Structures used in time services, primarily for getting time from a session server. 
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Program Construction and Execution 



A V-System C program is constructed and executed similar to a C program on Unix. 



14.1 . Writing the C Program 

An application program on the V-Systcm starts to execute as a single process^, with priority 4. It is allocated 
an initial stacic area of about 4000 bytes, just above its uninitialized data segment. If this is not large enough, 
one of the first actions of the team's root process should be to use die CreateO library function to create 
processes with larger stacks. 

Note that large dynamically allocated areas of memory should be allocated using malloc, calUx:, or a similar 
memory allocator, and not be allocated on Uie process stijck. Warning: There is no run-time checking for 
overflowing the proccsjj stack allocation. The program behavior from stack overflow can be sufficiently 
bizarre as to cause good programmers to seek refuge in monasteries. If die stack overflow caused the process 
in question to get an exception, the standard exception handling roudnc will usually detect die overflow and 
print a message: however, not all stack overflows cause an exception in die process that generated diem, and 
sometimes the stiick is back in bounds by the time die exception occurs. 

The file Venviron.h is a header file defining the types and constants diat arise as part of the interface to die 
kernel. It is included by die line 

i^include <VenvlPon.h> 
Other V header files, listed in die previous section, arc included similarly. 



14.2. Compiling and Linking 

When tlie application program is compiled and linked, references to kernel operations and other statidard 
routines must be resolved by searching die library file libV.a (kept in Aisr/sun/Iib on Stimford Unix 
systems). The application must be relocated so diat its text segment starts at 0x10000, These defaults are 
automatically selected with tlie -V option of die cc68 command. The compile command: 

cc68 -V -r programfna 

produces a .r file for nmning with die kernel. The program environment provided by die libV.a library is 
given in die later sections of tliis manual. 



14.3. Program Execution 

Hicrc arc two models for executing V C programs, namely: using the V executive and bare kernel mode. 



For a complete discussion of processes, message passing, and oUicr services provided by (he V Iccrncl. see the kernel manual. 
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1 4.3. 1 . Execution With the Executive 

Use of the V executive is described in the V-System commands manual. Basically, one types the name of 
the file containing the program to the command interpreter followed by zero or more command arguments. 
The program is then loaded and executed. 

When the V executive is used, the program execution begins at a procedure called ma1 n( ), passed a count 
of the number of arguments to llie program and an array of pointers to the program su-ing arguments, as 
given on the command line. Each new team is passed standard input, output, and error flics tiirough the 
Team Root message. 

The following example shows how a program can read its command line arguments. The variable argc 
contains the number of arguments including the command name. The arguments are Icept in argv[0] 
through apgv[argc-l]; the command name is argv[0], argvCl] is the first argument, 
argvCargc-1] is the last argument, and argv[argc] is null. This matches the Unix convention. 

ma1n( argc, argv ) 
Int apgc; 
chap •argvC]; 
/* Echo arguments */ 

C 

1nt 1; 

for( i ■ 0; 1 < argc; ++1 ) 

printf( "%s argvCI] ); . 
putchar("\n'') ; 

} 

The executive sets the new team's team priority to 30. 

14.3.2. Bare Kernel IVIode 

in bare icerncl mode, execution also begins at main(), but no arguments are available. 

None of tlie standard servers ordinarily included in the V executive are available, unless the program 
includes one or more of tlicm itself (as described in the V servers manual). 

A program to be executed In bare kernel mode is loaded by a special loader program called Vloaci: 
n VI cad 

typed to tlic SUN monitor causes it to load and execute tlie loader. (Use b in place of n on SMI 
workstations.) yioaJ then prompts for the name of a file containing die program. 'Hie use of this loader is 
described more fully in the Standalone chapter of tlie V commands manual. 



1 4.4. The Team Root Message 

l-!ach team is passed a team r(H)t message at the time it is started. This is die message passed to tlic team by 
Uic RaplyO call Ui:jt sets it innning. Hie team root mess*'igc is a stnicturc oflypc R(H)tMcssago, as defined 
in Llie st;uidard header file <Vteanis.h>. A function called TeainRoot() (aulonuitically included in every 
program by tlic -V option of ccfiS) receives die team nwt message, stores a copy of tlic team rt)ot nicss*ige in 
an area pointed to by die global variable RootMsg, initializes tlie team's stiindard i/o, and calls main(). If 
malnO returns, TeamRootO calls ex1t(). The team root message can be accessed from within a team 
(not usually necessary) by declaring it as 

extern RootMessage *RootMsg; 



Tlic team root message contains ilic following fields: 
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stdinserver Process id of the server providing this team's standard input file, 
stdoiitserver Process id of tiie server providing this team's standard output file, 
stderrscrver Process id of the server providing this tciun's standard error file, 
stdinfik Instance id of this team's standard input file, 

stdoutfile Instance id of this team's standard output file, 

stderrfilc Instance id ofthis team's standard error file. 

rootfiags A set of flags indicating whether the team is to overwrite or append to its standard output 

and standard error, whether standard input, output, or error have been redirected, and 
whether it is to release its standard input, output, or error instances upon exit. 

namcscrver Process id of the server providing the team's initial current coniext (i.e., current worlclng 
directory). 

contextid 'llie context id of the team's initial current context. 

kerncipid Process id to which the team is to send to obtain secondary kernel services (sec the V kernel 

manual). Normally the same as die team creator's kernel pid, provided the new team is 
running on the same workstation as its creator. 



14.5. The Per- Process Area 

Each process has a region of team memory reserved for its own use, called its stack space. On the Sun, a 
process's stack grows downward ft"om the highest address in this region. A portion of die stack space, called 
the per-process area, is used to store a few prtxiess-global variables. On tlic Sun, this area begins at die lowest 
address of the stiick region. A team-global variiibic called PorProcess points to Uiis area. It is reset by tlic 
kernel to point to tlic correct area on every process switch. 

The stondard per-pr(x;css area is described by Uic PerProccssArea structure in the header file <Vio.h>. It 
contains the follov^ing values: 



stdio 



nameserver 

contextid 

stackSize 



An array of three File pointers describing die prtxrcss's standard input, output, and error 
files. <Vio.h> defines die macros stdin, stdout, and stderp to be PepProc8ss-> 
std1o[0], PerProc9SS->std1oCl], and P9rProcess->std1o[2] respectively. 
Note Uiat only pointers, not the Kile structures Uicmsclvcs, arc kept in Uic per-process 
areas. 

Process id of die server providing die process's current context 
Coniext id of Uk process's current context. 
'I'hc size of die pnKcss's stack space, in bytes. 



The TdamRootC ) function inidali/cs the team root process's per-process area from die values passed in die 
team root messiigc. 'Hie Create () library function, used to create new prtKCsscs, inidalizcs each new 
process's per-process area to be a copy of diat of its creator (except for Uie stackSize field). This causes each 
child process to inherit its creator's standard I/O and current context. 
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The V-System Configuration Database 



15.1. Introduction 

When a diskless workstation boots up, it has a limited amount of information about its own configuration 
and identity. A boot program can probe to see what devices are attached, and some workstations may have 
configuration registcre, additional switches, or a small amount of nonvolatile memory. If a workstation has an 
Ethernet board, there will be a PROM or DIP switch on the board containing its Hdiernct address. I'here 
may also be some machine-specific information in PROMs on the processor board. If the workstation is 
booted by typing a command, rather than automadcally on power-up, the user may be asked to type in some 
information. 

From this information, the workstiition software needs to deduce several things, including at least: 
L What version of the kernel to load (68000, 68010). 

2. Which Ediernet board to use for interkemel communication, if there is more than one. 

3. What to run as die initial team. 

4. Whether to run the VG're, die STS, or some other program as the terminal server. 

5. What commands to execute before turning control over to the user, if any. (For example, we may wish 
to run a print server on this workstation, or automatically bring up an internet server in the 
background.) 

6. What Internet address to use for this workstation. 

7. What Uic name of this workstation is (e.g., SUN-MJ402). 

8. What type of tenninal is connected to the workstation, if Uic STS is to be used. 

In general, Uicrc is no reliable algorithm for determining most ofdicsc things. In fact, many are tlie result 
of essentially arbitrary human decisions- for example, die workstiUion name. 



15.2. Configuration Database 

As a solution to Uiis problem, die V-Systcm maintains a configuradon database, containing information 
about each workstation. 'ITic information is organized as sets of key word/ value pairs, one per workstiition. 

'Hicrc is one stiindard library function provided for extracting information from die configuration database: 



SystamCode QueryWorkstationConf 1g(koyword, value, maxlength) 
char •keyword, *va1ue; 
int maxlength; 

Given a character string representing Uie keyword, Uiis routine returns die corresponding value as another 
character string. The variable keyword points to the keyword, value points to the place to put Llic value, 
and maxlength is the si/e of die buffer, which should include space for a terminadng null byte. The routine 
returns a system error code if Uiere is no configuration information recorded for die querying worksuition 
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THE V-SYSTEM CONRGURATION DATABASE 



(NOT.FOUND), there is some configuration information, but no value corresponding to the given keyword 
(BAdIaRGS), or the buffer was too short to hold the value (BAD.BUFFHR). else returning OK. In the 
bufTer-too-shorl case, it will return as much as there is room for. In unusual situations, other error codes may 
be generated; these can be treated is failures or considered equivalent to NOT.FOUND. 



15.3. Impiementatioh 

Ordinarily, programs should not be aware of tlic implcmcntadon of the configuration database; this 
implementation may change in the fliture. The Query WorkstationConfigO fiinction should be the only 
interface used. Since there is no standard library function provided to modify the configuration database, 
however, system maintaincrs need to be aware of its implementation. The current implementation allows the 
configuration database to be modified with an ordinary text editor, and the changes installed with the same 
tools that are used for insitalling new binary program images on storage servers. 

The V configuration database is currently implemented as a set of configuration files, one for each 
workstation. Hach configuration file must be available on every publicaily-avatlable V storage server.^^ 
requests from nonlocal clients.) 

The name of each workstation's configuration file is derived from its hardware Ethernet address -a 
convenient unique identifier.'^ The files arc kept in a subcontcxt named "config", under the server's public 
context. (Sec section 30.) For a worlcstiUion with Ir^thernet address 0260.8c0 1.9954 (a typical 3Com-assigncd 
address), the configuration file could then be read by a workstation as a file named 
"Ipublic]config/C.02608c019954'*; this is in fact how Query WorkstationConfigO is implemented. 

A configuration file is an ASCII text files, consisting of a set of keyword/value pairs, arranged in no 
particular order. Each keyword appears at tlie beginning of a new line, and is separated from its 
corresponding value by a colon (*:'). A line beginning with a colon serves as a continuation of Uic value on 
the previous line. This format has been designed to be easy to read and easy to parse. (Note Unit spaces both 
before and after the colon may be considered significant by programs, so take care when creating or editing 
config files.) 

At Stanford, Uie master copies of configuration files are kept in the directory /xV/config on Pcscadcro, and 
only dwse copies should be edited. The command "make instiill" (nm as user ds) is used to install changes. 

Currently Defined Keywords 

I'he following keywords are in use at this writing. A list of keyword names and tlieir meanings is prescntiy 
kept in die same directory as tlie config files diemsclves, in a file called "keywords." 

name The name of diis workstation. Should match die name used in local IP name tiibles for diis 

workstation's IP address, 'llierc is no default 

ip-addrcss The workstation's Internet Protocol address, given in the conventional [a.b.c.d| notation, 
where a, b, c, and d arc decimal integers. On the 3 Mbit l:Uiernot, the default value of d is 
die 8-bit Etiiernct host address, while default values of a, b, and c are dctennined by the 
Internet server, i'or 10 Mbit Suns, diis keyword siiuuld always be present. 

ip-gatcways Name of a file containing a list of Internet gateways to be used by this workstation. Tlie 
file name is given relative to the standard [public] context If this keyword is omitted, die 
internet server will not forward datagrams through any gateways, Le., only local traffic will 



^^Publicaily-availablc storage servers arc defined as those Uial respond to GclPid(SrORAGli - SFRVCR, ANY- PID 

Currently, on Sun-2 workstalioiis with 3Coin [lUicrnel inter faces, the address assigned to the Ethernet board is u.sed. not tlic address 
assigned to the processor. 
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be supported 



kernel 



team 



world 

boot-options 
startup-script 



ait-ether^addr 



ndboot 



terminal-type 



Filename of the program to be loaded as the kernel, for use by Vload. The name is given 
relative to the standard [public] context. If tliis keyword is omitted, Vload uses a compiled- 
in dci'ault, currently Vkemel/sunl+en for the. 3 Mbit Ethernet version, Vkerncl/sun2H-ec 
for the 10 Mbit 

Filename of the first team, as above. If it is omitted, Vload uses a compilcd-in default, 
currently tcaml-vgts. 

Either V or xV. Used by Vload. If omitted, Vload uses a compilcd-in default, currently V, 

Boot options for use. by Vload. Currently the only option is b, meaning "break before 
starting kernel." The default is a null string. 

Filename of the startup script. Currently used only by teaml-scrvcr, for workstations that 
autoboot as servers. No default In the future, the definition of this keyword will be 
changed to allow the startup script to be placed directly in the config file, and all (or most) 
versions of the firet team will use it 

Alternate cthcmct addresses for this workstation, one per line. These arc addresses the 
workstation may use, other than the one the config file is named for. 10 Mbit addresses 
should be given in hexadecimal, in die form xxxx.yyyy.zzzz. 3 Mbit addresses may be 
given in octal. The default is null. 'ITiis keyword must be present for use by the Vax Unix 
ND server for workstations that boot using the ND protocol under a different Ethernet 
address than die one the config file is named for. This is true of SMI Sun-2's with PROM 
revision N or later. 

The Vax Unix ND boot server looks for a configuration file when deciding whether it 
should answer boot requests, and will reftise to respond if dicre is none or it contains die 
line "ndbootrno". ('ITiis procedure allows our ND server to coexist with SMI Network 
Disk servers on the same net) Thus, the default value for Uiis option is "yes" if a config 
exists for this workstation, otherwise "no." 

Type of terminal used as a console. Used by die STS. The default is to assume Uic 
Stanford PROM terminal emulator for Cadlincs, or something ANSI-compatible (like the 
SMI PROM terminal emulator) otherwise. 'Hie only other recognized value for Uiis option 
is"hi9". 



Usage 

In genera], we have implemented programs that use tliis service in such a way diat if a configuration file or 
specific keyword/value pair is missing, some reasonable default is used where Uiis is possible. Also, where it 
is easy to reliably determine something by examining die hardware present it is best to do that instead of 
putting die information in the configuration file. Following diese principles means Uiut fewer updates to die 
configuration files arc needed to keep workstations running correctiy when something changes. 

In some cases, the value of a keyword may be the name of a file, perhaps because it is more convenient for 
die client to read die information from a file, or because die information associated wiUi die keyword is quite 
bulky. In die present implemcntuion, such files are kept in die "[publiclconlig/" directory along witii the 
configuration files diemsclves. Files whose names begin with "S." are stiirtup command scripts for 
workstations that boot automatically. Files whose names begin with "G." are gateway information files used 
by die internet server. 
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— 16 — 
Input and Output 



The input and output routines can be divided into three categories: 

1. Basic I/O routines like getchar(} that arc supported but differ in their implementation from the 
standard Unix vei-sions. 

2. I/O support roudues lilce pr1 ntf ( ) that are identical with the standard Unix version. 

3. V-spccific I/O routines like Read() and Write() that are used in several cases to implement the 
standard C routines in the V message-based world. 



16.1. Standard C 1/0 Routines 



The following standard C I/O routines are available: 



chdIrO 
f error( ) 
fopen( ) 
f read( ) 
ftellO 
gets( ) 
putchar( ) 
scant ( ) 
ungetc( ) 



fflushO 
fprintf ( ) 
f reopen( ) 
fwrite( ) 
getw( ) 
puts() 
sprintf ( ) 



f close( ) 
fgetc() 
fputc() 
fscanf( ) 
getc( ) 
printf ( ) 
putw( ) 
setbuf ( ) 



feofO 
fgetsO 
fputsO 
f seek( ) 
getchar( ) 
putc( ) 
rewincl( ) 
sscanf ( ) 



However, fopen() returns a pointer value of type *Filc, where File is defined in <V}o.h> and is a totally 
dilTcrcnt record structure from tliat used by, for instance, the Unix standard I/O. Also, satbuf ( ) Is a no-op 
under V. 



16.2..V I/O Conventions 

Program input and output arc provided on files, which may include disk files, pipes, mail-boxes, terminals, 
program memory, printers, and other devices. 

To operate on a file, it is first "opened" using Open( ) if the file is specified by a pathname, otherwise by 
OpenFI le() ifUie file is specified by a server and instance identifier. The mode is one of the Ibllowing: 

1*RP,AD No write operations are allowed. File remains unchanged. 

l-'CREATB Any data previously asstwiated with the described file is to be ignored and a new file is tc 
be created. Doth read and write operations may be allowed, depending on the file type 
described below. 

FAPPEND DaUi previously associated with the described file is to remain unchanged. Write 
operations are required only to append data to tiie existing data. 

\'MOD\FY Rxisting data is to be modified and possibly appended to. Both read and write operations 
are allowed. 
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Both open functions return a pointer to an open file descriptor that is used to specify the file for subsequent 
operations. C1os9( ) removes access to the file, S8ek( ) provides random access to the byte positions in die 
file. Note: tiie value returned from a byte jposition that has not been written is not defined. 

Each program is executed with standard input, output and error output files, referred to as std1n, 
stdout, and stderr respectively. 

The file type indicates the operations that may be performed on the open file as well as the semantics of 
these operations. I'he file type is specified as some combination of the following attributes. 

READABLE The file can be read. 
WRITEABLE Tlie file can be written. 
APPEND.ONLY 

Only bytes after the last byte of die data previously associated with the file can be written. 

STREAM All reading or writing is strictly sequential. No seeking is allowed. A file instance without 

the STI^EAM attribute must store its associated data for non-sequential access. 

FIXED.LENGTH 

'ITie file instance is fixed in length. Otherwise the file instance grows to accommodate tlic 
data written, or the length of the file instance is not known as in Uie case of terminal input. 

VARIABLE.BLOCK 

Blocks shorter than the full bkx;k sixc may be returned in response to read operations other 
than due to cnd-of-file or other exception conditions. For cxample,^ input frames from a 
communication line may differ in length under normal conditions. 

With a file instance diat is VARIABLE.BI.OCK, WRITHABLK, and not STREAM, 
blocks that arc written with less tlian a full block size number of bytes return exactly the 
amount written when read subsequendy. 

MUL'n.BLOCK Read and write operations are allowed diat specify a number of bytes larger than die block 
size. 

INTERACTIVE 'ITie open file is a text-oriented stream. It also has die connotation of supplying 
interactively (human) generated input 

Not all of the possible combinations of attributes yield a useful file type. 

Files may also be used in a bltx;k-oriented mode by specifying FBI.OCK.MOOR as part of the mode when 
opening the file. No bytc-onented operations are allowed on a file opened in block mode. 

See die V'System Servers Manual for more details on the semantics of die various possible file types and 
modes. 



16.3. V 1/0 Routines 
16.3.1. Opening Files 



File •Open(pathnam9, mode, error) 

char *pathnaine; unsigned short mode; SystemCode ^error; 

Open die file specified by pathname widi die specified mode and return a file pointer for use with 
subsequent file operations. 
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mode must be one of FREAD, FCREATE, FAPPEND, or ['""MOOfFY, with FBLOCK^MODK if block 
mode is required. If OpQn() fails to open die file, it returns NULL and the location pointed to by error 
contains a standard system reply code indicating die reason. If an error occurs and error is NULL, Open() 
calls abort(). 



File *OpenFile(sdrver, instanceidentif 1er , mode, error) 
Processid server; Instanceld instanceidentif ier; 
unsigned short mode; SystemCode *error; 

Open the file instance specified by the server and instanceidentif Ier arguments and return a file 
pointer to be used with subsequent file operations. 

mode must be one of FREAD, FCREATE, FAPPEND, or FMODIFY, with FBLOCK.MODE if block 
mode is required. If the instance is to be released when C1ose() is called on tliis file pointer, 
FRELEASE_ON_CLOSE must also be specified as part of the mode. If OpenF 1 1 e ( ) fails to open the file, 
it returns null and die location pointed to by error contains a standard system reply code indicating die 
reason. If an error occurs and error is null, OpenFi 1e( ) calls abort( ). 



File •_Open(req, mode, server, error) 

CreatelnstanceRequest *req; unsigned short mode; 
Processid server; SystemCode 'error; 

Open a file by sending the specified I/O protocol request message req to the server specified by server and 
return a file pointer to be used with subsequent file operations. This function is only used when addidonal 
server-dependent information must be passed in the request message, or die file is to be opened on a server 
diat cannot be specified by a character string pathname as in Open () . 

The request req may be either a CreatelnstanceRequest or a QuerylnstanccRequesL mode must be one of 
FRKAD, FCRHATE, FAPPHND, or FMODIFY, widi FBLOCK.MODH if block mode is required. If 
_Open^) fails to open die file, it returns NULI, and tlie location pointed to by error contains a standard 
system reply code indicating the reason. If an error occurs and error is null, _Open( ) calls abort ( ). 

SystemCode CreatoInstance(pathname, mode, req) 

char 'pathname; unsigned short mode; CreatelnstanceRequest *req; 

Open die file specified by pathname in die given mode using die specified CreatelnstanceRequest, but do 
not set up a File structure for it A CrcatelnstanccReply is returned at die location pointed to by req. The 
function returns a standard system reply code, which will be OK if die opcradon was successful. 

1 6.3.2. Closing Files 



Close(fne) 

File 'file; 

Remove access to Uic specified file, and free the storage allocated for die File stmcture and associated buffers. 
If die file is WRITEABLH and not in FBLOCK.MODE, die output buffer is flushed. 

Spec1a1C1ose(f He, releasemode) 

File 'file; unsigned releasemode; - 

Close die specified file,, as in C1ose( ). If SpecialClose( ) releases the file insuincc associated with die 
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specified File structure, the release mode will be set to releasemoda. Closa( ) sets the release mode to 
zero. Sec the I/O protocol section of the V servers manual for a explanation of release modes. 



Releaselnstanc8(f lleserver, fileid, releaseinode) 

Procsssid fileserver; Instancald fileid; unsigned releasemode; 

Close the flic instance specified by fileserver and fileid, using tlic specified release mode. This 
flinction is used only when there is no File structure for die given file. 

16.3.3. Byte Mode Operations 

The standard Unix functions mentioned above may be used on files opened in byte mode (i.e., not opened 
in FBLOCK.MOOE). Several other functions are also available on such files, as described below. 



int Seek(file, offset, origin) 

File ♦file; int offset, origin; 

Set the current byte position of the specified open file to that specified by offset and origi n and return 
TRUK (nonzero) if successful. 

If origin is ABSJJf.K or ABS_BYIU the byte position is set to the of f set-th block or byte in the file 
starting from 0. If origin is RHL.BYTK, offset specifics a signed offset relative to die current byte 
position. If origin is F1LH_HND, offset is the signed byte offset from the end of file. 

If die file is KIXHD.LENGTH, an attempt to seek beyond die end of file causes Seek to return FALSE 
and the byte position to remain unchanged. The end of file position is one beyond the last byte written. The 
value of bytes in the file previous to die end of file Uiat have not been cxpllcidy written is undefined. 

Seek( ) may not be used on files opened in block mode. SeekBloGk() should be used on such files. 
Seek( ) is idendcai to f seek( ). 



unsigned BytePosition(file) 
File -file; 

Return Uie current byte position in die spccilled file. The value returned is correct only if Uic current byte 
position is less than MAX^UNSIGNRD. This function is identical to f tel 1 ( ). 

Flush(file) 
File- •file; 

Flush any buffered data associated with the file, providing it is WRITEABLK. Flushing a file causes local 
buffered changes to die file datii to be comnuniicatcd to die real file. If die file is in block mode or not 
WRfrHABLE, no action is performed. 'Hiis function is identical to ff lush( ). 



Resynch(f ile) 
File 'file; 

Resynchronizc die next block to read and write in die file with the server. Any buffered bytes are lost. Tliis 
operation is only valid for streams, and is only needed when diere is more than one File structure associated • 
with a single file instance. This will happen, for example, if two tctims arc sharing die same standard output. 
Normally it should not be needed for files used in a single team. 
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SystemCode Eof(file) 
File 'fne; 

Any of the byte mode read or write operations may return EOF (Exception On File) as a special value 
indicating an inability to read or write further in the file. Eof returns a standard system reply code indicating 
the nature of the exception. This may be a true end-of-file, i.c., the current byte position exceeds .the last byte 
position of the file, or some type of error. 



CleapEof(fne) 
File •file; 

Clear the exception on the specified file. 'ITiis only clears the local record of Uie exception; it does not affect 
the circumstances that caused the exception to occur. See Eof ( ) . 

1nt BufferEnipty(irne) 
File •file; 

Test whether or not a file's local buffer is empty. If tliis function returns TRUE (nonzero), the next getc( ) 
will cause an actual read. If it returns FAI.SE (zero), tlic next getc( ) will return immediately with a byte 
from the buffer. 

1 6.3.4. Block Mode Operations 

The following ftmctions arc most useful on files opened in block mode. Unless otherwise noted, they may 
also be used on files opened in byte mode. 



unsigned ReadCfila, buffer, bytes) 

File *fne; char •buffer; unsigned bytes: 

Read the specified number of bytes from the file starting at die beginning of the current block location of die 
file and store contiguously into the byte array starting at buffer, returning die actual nuiiibcr of bytes read. 

If the number of bytes read in less than- the number of bytes requested, Uie reason is indicated by die 
standard reply ccxie returned by FileException( ). The number of bytes requested may not be more Uian 
die block size of the file (returned by BlocicSize( )> unless Uie file has Uic type attribute MULTLBLOCK. 
Read( ) is intended for use on files opened in block mode only. Note: Read() docs not increment Uic 
current block number stored in die File structure fur die given file. 



unsigned Write(f11e, buffer, bytes) 

File «file: char •buffer; unsigned bytes; 

Write Uic spcciTicd number of contiguous bytes from die buffer to die file starting at die beginning of die 
current block location of Uic file, and return the actual number of bytes written. 

The number of bytes to be written must be less Uian or equal to die bl(x:k size (as returned by 
BlockSizaO) unless die file has die type attribute MULTlJiLOCK, If die number of bytes written is less 
dian die number of bytes requested, die reason is indicated by the standard reply code returned by 
FileExcaption(). 

Wr1te() should be used only on files opened in block mode. Note: Write() does not increment die 
current bjock number stored in die File stnicturc for die given file. 
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unsigned BllcsInFna(f ild) 
File •file; 

Return the nuniber of blocks in tlic specified file. Mcaningflil if tlie file is FIXED.LENGTH or is a 
WRH EABLE non-VARIABLE^BLOCK, STREAM file, 

unsigned B1ockPosition(f i1e) 
File 'fne; 

Return the current block position in the specified file. 

SeekBloc!c(f ile, offset, origin) 

File 'file; int offset; int origin; 

Set tl\e current block position of the specified open file to that specified by origin and offset. The new 
block position is the block offset from the specified block origin, origin is one of FILE_UEGINNING, 
FU.R.END or FILE.CURRENT.POS. 

unsigned BlockSize(f ile) 
File 'file; 

Rctuni the block si/u in bytes of Uie specified file. 

unsigned Fi1eException(f ile) 
File 'file; 

Return the standard reply code indicating the last exception incurred on Uie specified file, lliis is used 
primarily on files opened in FBLOCK^MODR. Eof ( ) is used on byte-oriented files. 

16.3.5. Server-Specific Operations 
This section describes routines in. Uie I/O library which are specific to particular servers. 

SystemCode CreatePipeInstance(readOwner, writeOwner, buffers, reply) 
Processid readOwner, writeOwner; int buffers; 
CreatelnstanceReply •reply; 

Interact with the pipe server to create a pipe, with the specified owners for the reading and writing ends of tlie 
pipe, and the specified number of buffers, buffers should be between 2 and 10 Inclusive. The reply to the 
create instance request is returned at die location pointed to by reply: it contains the file instance id of the 
wriieabie end of the pipe. 'I1ic id of the readable end is equal to Uiis value plus 1. OpenFi le( ) may be used 
to set up File stnictures for eiUier of both ends of Uic pipe. CreatePipeInstance( ) returns a standard 
system reply code, which will be OK if Uie operation was successful. 



File •OpenTcp(localPort , foreignPort, foreignHost, active, 
precedence, security, error) 
unsigned short localPort, foreignPort; unsigned long foreignHost; 
int active, precedence, security; SystemCode 'error; 

Interact with Uic Internet server to create a TCP network instance, and return a pointer to a File structure 
opened in byte mode Uiat can be used to send data .on Uic corresponding TCP connection. 
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To obtain a second File structure that can be used to read from the connection, use the call 

f2.« OpenFile(Fil8Sepver(fl) , Fileld(fl) + 1, 
FREAD +. FRELEASE.ON^CLOSE. &ePPor) 

where fl is the value returned by OpenTcp(). Note that it is necessary to release both the readable and 
writcable instances to cause the connection to be deallocated. Releasing the writeable instance closes the 
caller's end of the connection. Data can still be read from the readable Instance until it is released, or other 
end closes (resulting in an END.OF^FI LK indication). 

The parameters TocalPort, forelgnPoPt, and forelgnHost specify die sockets on which the TCP 
connection is to be opened, active specifies whether the connection should be active (i.e., send a 
connection **syn" pacltet), or passive (i.e., listen for an incoming "syn" packet), ppecedence and 
security specify the precedence and security values to be used for the connection. Specifying zero for 
these parameters will cause appropriate default values to be used. 

If the open is unsucccssfiil, OpenTcp( ) returns null, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 



File *OpenIp(ppotocol , 9ppop) 

chap ppotocol; SystemCode •eppor; 

Interact with the Internet server to create an IP network instance, and return a pointer to a File structure 
opened in biock mode ttiat can be used to write IP packets to the network. 

To obtain a second File structure tliat can be used to read IP packets, use the call 

fl - OpenFn8(FneS8rvep(fl), Fileld(fl) ■»• 1, 

FREAD + FBLOCK^MODE + FRELEASE,ON„CLOSE , &erPor) 

where fl is the value returned by OpenIp(). Note that it is necessary to release both the readable and 
writcable instances even if only one of tliem is used. 

The ppotocol specifics which value of the protocol field in the IP packet headers is of interest. The 
readable instance will only return packets with the requested protocol value, and Uic client program should 
only write packets with the specified protocol field to tlic writeable instance, though this is not currently 
checked by the server. If ppotocol is zero, it specifics "promiscuous" mode, in which ail IP packets are 
returned which are not of protocol types tliat have been requested by another cllcnl, and packets of any 
protocol type may be written. 

If the open is unsuccessful, OpenIp() returns null, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by epror; else OK is returned in tliis location. 



File *OpenPup( socket, error) 

unsigned long socket; SystemCode *error; 

Interact with the Internet server to create a PUP network instimcc, and return a pointer to a File structure 
opened in block mode iliatcan be used to write PUI's to tiic network. 

To obtain a second File structure tliat can be used to read PUPs, use Uic call 

f2 « OpenFne(F1l8SePvep(fl). Fileld(fl) + i, 

FREAD + FBLOCK^MOOE + FRELEASE.ON^CLOSE , iePPOP) 

where f l.is the value returned by OpenPup( ). Note that it is necessary to release both the readable and 
writcable instances even if only one of them is used. 

The socket parameter specifies which value of the socket field in the PUP headers is of interest. The 
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readable instance wilt only return packets sent to tlic requested socket, and the client program should only 
write packets widi tlic specified source socket to the writeable instance, diough this is not currently checked 
by the server. If socket is zero, it specifies "promiscuous" mode, in which all PUPs arc reairned which are 
not to sockets that have been requested by another client, and packets with any source socket number may be 
written. 

If tile open is unsuccessful, OpenPup() returns NULL, and a standard system reply code indicating the 
reason for failure is returned in the location pointed to by error; else OK is returned in this location. 

1 6.3.6. Miscellaneous I/O Functions 

Instance-Id Flleld(file) 
File •file; 

Return the file instance identifier associated with the open file, lliis was eidicr generated as part of Open( ) 
or specified as an argument tothcOpenF1le() operation that opened the file. 

Prodessid FneServer(f ile) 
FUe •file; 

Return the file server identifier associated with the open file. This was cither generated as part of Open ( ) or 
specified as an argument to the OpenF i 1 e ( ) operation that opened the file. 

unsigned FneType(fne) 
File •file; 

Return die file type, which indicates die operations that may be performed on the open file as well as die 
semanUcs of these operations. 

unsigned Interact1ve(f 11e) 
File •file; 

Return TRUK (non/.cro) if die file has Uic type attribute IN TKRACnVR, else I' ALSH (zero). 

File •OpenStr(str , size, error) 

unsigned char *str; unsigned size; SystemCode *error; 

Make the specified string look like a file. The file is FIXHD.LENGTH, with one block of size size, and die 
end of file set to die end of Uiis block, str must point to an area at least size bytes in lengUi. A file opened 
by OpenStr( ) is idendfied as such by its file server (us returned by F1 1 eServer ()) being equal to 0. 

SystemCode ReinoveF11e( pathname) 
char 'pathname; 

Remove (delete) die file specified by pathname. 

SystemCode SetBreakProcess(f lie, breakprocess) 
File *f11e; ProcessId breakprocess; 

Sets die break process associated with die specified file (which must be INTERACl'IVB) to breakprocess. 
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If a break occurs on the file after a break process has been set, the lO^BREAK reply will be returned to any 
outstanding read requests, land the specified break process will be destroyed. 

SystaraCode SetInstanceOwner(f ileservop , fileld, owner) 
Processid fnaserver, owner; Instancald fHaid; 

Set the owner of the specified file instiince to be owner. 

Pr1ntFne(name, file) 

char *naine; File •fUej 

Print the value of each field in the given File structure on the standard output, identifying the file by the 
name name. Useful in debugging servers and I/O routines. 

SystamCode ChangaOl rectory (name) 
char *naine; 

Change tlie current context for the calling process to be the context specified by name, and return a standard 
system reply code indicating OK if successful, else the reason for failure, name is interpreted in the 
(previous) current context. This function is identical to chd1r( ), except tliat die latter returns 0 to indicate 
success or -1 to indicate failure. 
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Numeric and Mathematical Functions 



17.1. Numeric Functions 

Most of the flinctions in the numeric section of tlie library are not called directly in user prognims; tliey are 
accessed by tiic C compiler as needed. ITic following functions are useful in user programs: 

unsigned abs(value) 
1nt value 

Integer absolute value. 
1nt rand() 

Random number generator. Generates pseudo-random numbers in the range from 0 to This is a very 
poor generator, identical to the one provided in Berkeley Unix 4.1. 

srand(seQd) . ' 

unsigned seed; 

Rcseed tlie pand( ) random number generator. 

17.2. Mathematical Functions 

Tlic matli-rciatcd functions in the V library arc listed below. They are similar to die "section 3M" functions 
of tlic Unix library. Sec Uie Unix manual for documenUition. 



sin()' cos() tan() asin() 

acos() atan() atan2() sinh() 

coshO tanhO jO() 

jn() yO() yl() yn() 

hypotO cabs() ganima() fabs() 

foot() C91T() exp() log() 

loglO() pow() sqrt() 
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Memory Managemeni 

Blocks within a managed pool of memory can be dynamically allocated and freed within the address space 
of a team using the functions described below. Note that there is one pool of free storage for all processes in 
the team. Programmers must be careftil to synchronize the processes allocating and freeing this storage. 
These routines provide essentially the same functionality as the standard C library. 1'he memory allocation 
routines arc provided on a per-tcam basis. 

char *inal1oc(s1ze) 
unsigned size; 

Returns a pointer to a memory block that is size bytes long. NUI.L is returned if dicre is not enough 
memory available. 

fP9e(ptr) 

chap •ptpj 

The memory pointed to is returned to the free storage pool. ptP must point to a block allocated by one of the 
routines listed, here. ' 

char *P9anoc(ptr, size) 

char 'ptp; unsigned size; : 

Changes the si/e of the block pointed to by p tp to be s 1 ze bytes. Returns a possibly moved pointer. 

chap *calloc(eTeinents, size) 
unsigned elements, size; 

Bquivalcnt to mal 1oc(elements*s1ze), except' th(i area is cleared to zero. Provided for allocating arrays 

cfpee(ptp, elements, size) 

chap •ptp; unsigned elements, size; m 

Frees storage allocated by cal loc(). Actually, this function is identical to tpee(ptp), which may be usc( 
instead, el ements and size are ignored. 

: ■ :• ■ ] ■ ••:) I t 

< ! : 1. 

unsigned Copy( destination, soupce, count) 

chap *desti nation, *soupce; unsigned count; 

A block transfer function. Transfers count bytes from souPce to desti nation. Returns count. 

unsigned blt(dest1nation, source, count) 

chap ^destination , *souPce; unsigned count; 
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Identical to Copy (). 

char •Zero(ptr, n) 

char •ptr; unsigned n; 

Zero memory. Writes n bytes of zeros starting at ptr, and returns ptr. 

c1ear(ptr, n) 

char *ptr; unsigned n; 

Clear memory. Writes n bytes of zeros starting at ptr. 

swab(pfroni, pto, n) 

char •pfrora, •pto; unsigned n; 

Swap the bytes in n 16-bit words starting at the location pf Pom into a block starting at tiic location pto. 

Tlie following functions are of interest only to tliose managing memory (using tJie kernel primitives) in 
addition to that provided by the above routines. The current implementation of mal loc() prevents these 
routines from adding space below the current top of die pool. 

(i1veToMa11oc(start, length) 
char 'start; Int length; 

Add the length bytes of memory at start to the piwl used by the allocators described above, returning the 
number of bytes actually insuiUed after alignment and error-checking is done. 

char * (3etMoreMallocSpace(m1n, actual) 
1nt min. *actual ; . 

MallocO calls this iimction to acquire more space tor its pool; a default version is supplied, which is 
replaced if the programmer supplies a routine of this name. GetMoreMal locSpace() should return a 
pointer to at least ml n bytes of space and set *actual to the number of bytes made available; NULL may be 
returned if no more space is to be added to the pool. 

In the default version, free memory is determined and extended b<ised on the memory map and memory 
usage of die team (using tlic V kernel operations GetTeainS1ze( ) and SetTeaniS1ze( )). 
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Processes and Interprocess Communication 



The process-related functions in the V C library provide services and/or interfaces between processes and 
the Y kernel. They have no direct analog in the standard Unix C library. 



1 9. 1 . Ke rnel Ope rations 

These functions provide; a convenient interface to kernel-provided services. Some of the functions execute 
kernel trap instructions, while others send messages to a pseudo-process inside the kernel.. 

A kernel operation executes as a single indivisible fiinction call as far as the C programmer is concerned. 
Each kernel operation tiikcs zero or more arguments and returns a single value. 

In the descriptions below, the active process or invoking process always refers to the process that executed 
the kernel operation. 

Some operations such as SetTcamPriority and SetTime are intended to be used only by "operating system" 
or management processes and should not be used by application programs. 



Int AwaitingR8p1y(f pompid, awa1t1ngpid) 
ProcQSsId frompid, waitingpid; 

Return true (nonzero) if awaltingpid is awaiting reply from f romp id; otherwise return false. Note: if 
awaltingpldis send blocked on f rompld, but f ponipid has not yet received the message, tliis function 
will return false. 



Procassid Cr9atof(pid) 
Procassid pid; 

Return the process id of the process diat created pid. If p1d is zero, return the creator of tlie invoking 
process. If p 1 d does not exist or is the root process of tlie initial team, return 0, 

Procassid Creat8Procass(pr1ority, initlalpc, initlalsp) 
short priority; char •initlalpc, •initlalsp; 

Create a new process with die specincd priority, initiul program counter and initial stcick pointer and return its 
unique process idenlifier. 

The priority must be between 0 and 127 inclusive, with 0 the highest priority. 1 n 1 1 i al pc is die address of 
the first instruction of the process to be exeaited outside of the kernel. Generally, initlalsp specifies tlic 
initialization of the stack and general registers and is pn^essor-spccific. In the case of tlie Motorola 68000, 
initlalsp isa simple long word value that is assigned to the user stack pointer. 

The process is created awaiting reply from tlie invoking process and in the same team space. The scginent 
access is set up to provide read and write access to the entire team space of die newly created process. The 
creator must reply to tlie- newly created process bcl'orc it can execute. If tlierc are no resources to create the 
process or the priority is illegal, a pid of 0 is returned. 
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Usually programmers will prefer the Create ( ) call described later in this chapter. 



Ppocessid CreateTeain(pplbp1ty, inltialpc, Inltiaisp) 
short priority; char «1n1t1alpc, •1n1t1alsp; 

Create a new team with inidal or root process having the specified priority, initial program counter, and initial 
stack pointer. 

Cr8ateTeain( ) is similar to CreateProces3( ) except the new process is created on a new team. The 
new team inidally has a null team space. It is intended that the creator of tlic team will initialize die team 
address space and root process state using SetTeainS1ze( ), MoveTo( ), and Wr 1 teProcessStat8( ). 

CreateTcam returns 0 if there are no resources to create the team or the root- process, or the priority is 
illegal. 



Oelay(sdconds. clicks) 

unsigned seconds, clicks; 

Suspend die execution of the invoking process for the specified number of seconds and clicks (where a click is 
a machine-specific unit, usually onc ciock interrupt). 

Del ay ( ) returns 0 after the time period has passed, or die number of clicks remaining in die delay time if 
die process has been unblocked by Wakeup ( ) . A clock interrupt on the SUN workstation is 10 milliseconds. 



SystemCode DestroyProcess(pid) 
Process Id pid; 

Destroy the specified process and all processes diat it created. When a process is destroyed, it stops executing, 
its pid becomes invalid, and all procesises blocked on it become unblocked (eventually). 

DestroyProcessO returns OK if pid if successful, else a reply code indicating die reason for failure. 
DestroyProcess(O) is suicide. 

Usually programmers will prefer die Destroy( ) call described later in this chapter. • 



Processid Forward(insg, frompid. topid) 

Message msg; Processid frompid* topid; 

Forward die message pointed to by msg to the process specified by topid as though it had been sent by die 
process f romp id. 

The process specified by f rorapid must be awaiting reply from the invoking process. The effect of diis 
operation is dicsiimc as if f romp id had sent directly to topid, except Uiat die invoking process is noted as 
die forwarder of die message. Note diat Forwar d( ) docs not block. 

ForwardO returns topid if it was successful, 0 if unsuccessful. If topid is invalid, frompid is 
unblocked with an indication that its Send () failed. 



Processid Forwarder(pid) 
Processid pid; 



^^Proccsscs blocked on a nonexistent processes arc detected and unbloclced by the dock interrupt rouUnc checking periodically. 
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Return the process id that forwarded the last message received from p 1 d, providing p1 d is still awaiting reply 
from the invoicing process. If the message was not forwarded, p1 d is returned. If p i d does not exist or is not 
awaiting reply from the invoking process, 0 is returned. 

ProcQssId GetP1d(1ogica1id, scope) 
1nt logicalid, scope; 

Return the pid of the process registered using SetPi d( ) with the specified logi cal 1 d and scope, or 0 if 
not set 

The scope is one of: 

LOCAL^PID Return a locally registered process only. 

REMOTE.PID Return a remotely registered process only. 

ANY.PID . Return a local or remote process pid. 

Iflog1cal1dis ACnVE.PROCESS, the pid of the invoking process* is returned. If a scope of remote is 
specified, the kernel broadcasts a request for a process identifier registered as this logical id to other 
workstations running tlie V kernel on the network. If the scope is any, the kernel first looks for a locally 
registered process: if one is not found, it then looks for a remote process. In this way, a kernel can discover 
the process identifiers of the standard server processes from otiicr kernels, or at least from tlie kernel that is 
running the server process of interest 

Processid GetTeamRoot(pld) 
Proce^sld pid; 

Return the process identifier of die root process of the team containing pid, or zero if pid is not a valid 
process identifier. A pi d of zero specifies the invoking process. 

chap •GetT9ainSi29(p1d) 
Processid pid; 

Return the first unused location in tlic team space associated with p i d, as set by Se tTeamS i ze ( ) . I f p i d is 
/.cro, tlic si/c of the invoking process's team is returned, if p i d does not exist 0 is returned. 

unsigned GetTime(clicksptr) 
unsigned *clicicsptr; 

Return die current time in seconds. The standard is to represent dmc as seconds since January 1, 1970 GMT. 
If c1 i cksptr is not null, tlic number of clock interrupts since the last second is stored at that location. 

SystemCode MoveFroin(srcpid , dest, src, count). 

Processid srcpid; char *dest, ""src; unsigned count; 

Copy count bytes from the memory segment starting at src in the' team space of srcpid to the segment 
starting at dest in die invoking process's space, and return die standard system reply code OK. 

The srcpi d process must be awaiting reply from the invoking process and must have provided read access 
to tlie segment of memory in its space using the message format conventions described for Send(). 
MoveFrom( ) returns a standard system reply code indicating the reason for failure if any of tlVcse conditions 
arc violated. 
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SystemCode MoveTo(clastpid, dest, src, count) 

Procassid destpid: char *dest. *src: unsigned count; 

Copy count bytes from the segment starting at src in the invoicing process's team space to the segment 
starting at des t in the team space of the destp 1 d process, and return tlie standard system reply code OK. 

The destpid process must be awaiting reply from the invoicing process and must liavc provided write 
access to the segment of memory in its space using the message format conventions described under Send( ). 
MoveTo( ) returns astandard system reply code indicating the reason for failure if any of these conditions are 
violated. 

QuepyKernel(p1d, groupSelect. reply) 

ppocessid pid; 1nt groupSelect; Message reply; 

Query the kernel on the host where process p1d is resident A pid of zero specifies the invoking process's 
kernel, v 

The groupSelect field specifies what information is to be returned in the reply message. The available 
group selection codes arc MACHINH- CONFIG, to return information about Uie prwcssor configuration, 
PHK1I>!IHRAI. -CONFIG, to return a list of peripherals available on Uic machine, KFR NFL -CON FIG, to 
return the kernel's configuration parameters, M KM OKY — STATS, to return memory usiigc statistics, and 
KHRNIU.— STA TS, to return other kernel statistics. 'Hicsc codes, and tlic corresponding structures tliat may 
be returned, arc defined in tlie standard header file <Vquerykemcl.h>. 

Processid QueryProcessState(p1d, pb) 
Processid pid; ProcessBlock 'pb; 

Copy the state of the process into die structure pointed to by pb. 'llie various fields in the structure are 
defined in <Vpn)cess.h>. Their meanings should be self-explanatory. 

ITic message buffer is only available if p1d is Uic invoking pnx:ess or is awaiting reply from the invoking 
process;. If not, the appropriate fields in the structure are /.croed. 

If pid is zero, die priK-css st!Uc of die invoking process is returned. If pid does not exist, 0 is returned; 
otherwise, pid is returned. 

Processid ReadProcessState(pid, state) 

Processid pid; Processor.state *state; 

Copy die machine-specific processor state into die stnicture pointed to by state. The information returned 
is a subset of diat returned by QueryProcessStata( ). 

If pi d is zero, die processor state of die invoking process is returned. If pi d docs not exist, 0 is returned; 
otherwise, p1d is returned, 

Processid Receive(nisg) 
Message msg; 

Suspend the invoking process unUl a message is available from a sending process, returning die pid of diis 
process, and placing Uic message in the array pointed to by msg. 

Processid ReceiveWithSeginent(nisg, segbuf, segsize) 
Message msg: char *8egbuf: unsigned *segs1z8; 
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Suspend tlic Invoking process until a message is available from a sending process, returning die pid of tliis 
process, and placing the message in the array pointed to by msg and at most tlie first 'sags I29 bytes of tlic 
segment included with the message in tlie buffer starting at segbuf . The actual number of bytes in tlie 
portion of the segment received is returned in 'sag size. 

Procassid RecalvaSpacif ic(msg, pid) 
Massaga msg: Procassid pid; 

Suspend tlic invoking process until a message is available from the specified process, returning the pid of this 
process, and placing the message in the array pointed to by msg. 

If pid is not a valid process identifier, ReceiveSpecific returns 0. 

Procassid Reply(insg, pid) 

Massaga msg; Procassid pid; 

Send the specified reply messiigc to the prwess specified by pi d and return pid. 

The specified process must be awaiting reply from die invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. 

Rap1yWithSagment(insg, pid, src, dast« bytas) 

Message msg; Processid pid; char *src, *dest; unsigned bytas; 

Send die specified reply mess«ige and segment to die pnxiess specified by p i d and return pid. 

The specified process must be awaiting reply from the invoking process. Zero is returned if the process 
docs not exist or is not awaiting reply. The segment size is currently limited to 1024 bytes. A 
RaplyWi thSagmentO with a nonzero segment size may only be used to reply to an idcmpotent request 
(sceSendO). 

RareadM$g(msg, pid) 

Message msg; Processid pid; 

Reread into msg die message received from die process specified by pid, providing it is still awaiting reply 
from the invoking process. 

ReraadMsgO copies the contents of die message buffer last received from pid Into die array msg, 
providing die pr(x:ess specified by pid still exists and has not been replied to. If pid is zero. It Is taken to 
mean die invoking pr<x:ess and rereads the last reply message. 'ITiis opcmtion also allows a newly created 
process to read die initial reply message from its creator. 

int SameTaam(pidl. pid2) 
Processid pidl, pidZ; 

Return true (nonzero) if die processes specified both exist and arc on dic same team; otherwise return false. 
If eidier pid is zero, die invoking process is assumed. 

Processid Send(msg. pid) 

Message msg; Processid pid; 

Send die message in msg to die specified process, blocking die invoking process until die message is both 
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received and replied to. The array specified by msg is assumed to be 8 long words. 'ITic reply message 
overwrites tlic original message In the array. 

If Send 0 completes siiccessftilly, it returns the pid of the process that replied to the message. The pid 
returned will differ from that specified in the call if tlic message is forwarded by the receiver to another 
process that in turn replies to iL If the send fails (for instance, because tlic intended receiver docs not exist), 
Send( ) returns the pid of die process the message was last forwarded to (the pid it was sent to, if it was never 
forwarded). The kernel indicates the reason for the failure by overwriting the first 16 bits of the message with 
a standard system reply code. (This places it in the replycode field for reply messages that follow the standard 
system fonnaL) 

Ail messages must follow the kernel message format conventions as follows. The first 16 bits of the message 
are considered to be a request code or reply code. The highest order 6 bits are assigned special meanings. 

Bit 0 is 0 if a request message is being sent, or 1 if a reply message. 

Bit 1 is 1 if die request code or reply code is considered a standard system code. Applicadons 

can use special request codes and reply codes internal to their programs but use standard 
ones for interfacing to other programs and the system. Tlie remaining 4 bits are 
interpreted with the following special meanings only if the message is a request 

Bit 2 is 1 if tlic request is considered to be idcmpotcnt. This is just a hint to discriminate 

between requests tliat do not need duplicate suppression and tliosc tliat do. 

Bit 3 is 1 if the request specifies a segment. If 1, the kernel interprets the last 2 words of the 

message as specifying a pointer to the start of the segment and the si/e in bytes of tlie 
segment, respectively. 'ITic kernel tlien makes the segment available to die receiving 
process using MoveTo and Movel-'rom. Access to the segment is controlled by the 
following two bits, which only have meaning if bit 3 is 1. 

Bit 4 > is 1 if read access is provided to die segment 

Bit 5 ' is I if write access is provided to the segment 

It is intended and assumed that most requests can be iissigned a request code Uiat is stored in the first 16 bits 
of die request messiige, so that the bits are set correctly for die request by tJie value of die request code. 



SetPid(logica1 id, pid. scope) 

int logicalid. scope; Processld pid; 

Associate p1d with tlic specified logical id within the spccifcd scope. Subsequent calls to GetPid() with 
this logical Id and scope return Uiis pid. 'litis provides an efficient low-lcvei naming service. 

The scope is one of: 

L0CAi..Pll3 Register the process in die local scope only. 

RHMOTHJ'IO Register die process in the remote scope only. 

AN Y.PID Register die process in botli die local and remote scopes. 

The local scope is intended for servers serving oitly die local workstation. The remote scope is for netwt)rk- 
acccssed server processes serving several workstations (but not the local workstaUon). Hie any scope permits 
bodi local and remote access. 



SetTeamPriority(p1d, priority) 

Processld pid; short priority;' 
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Set the team priority of the team associated with p1d to the specified priority and return tiie previous team 
priority. 

Each prcxiess cfTcctivcly runs with the absolute scheduling priority of its team's priority plus the priority 
specified when die process was created. SetTaamPPiorityC ) changes die absolute scheduling priority of 
each process on die team by modifying die team priority. 'Vhis operation is intended for implemendng 
macro-level scheduling and may eventually be restricted in use to die first team. 

If p1d is /.ero, die invoking process's team priority is set 



char •SetTeamS1zo(p1d, addr) 
Procassid pid; char •addr; 

Sets the first unused address for die team containing pid to addr. The new team size may be cidicr greater 
or smaller than die previous size. The new team size is returned; diis will noiTnally be equal to addr. If there 
was nut enough memoiy available to grant die request, the return value will be less dian addr: if addr was 
below die suirting address for team spaces on the host machine, die team space will be set to null and its 
starting address will be returned. Thus Se tTeamS 1 za ( p i d » 0 ) is a machine- independent way of setting a 
team space to null. 

A pid of 0 specifies die invoking pr(x:css. Only- die creator of die team or members of the team may ciiange 
die team size and (consequently) die specified process must be local. 



SotT1me( seconds, clicks) 

unsigned seconds, clicks; 

Set the kernel-maintained dme to diat specified by seconds and cl icks. 

The stiuidiird dmc rcprcsentaUon used is die number of seconds since January 1, 1970 GM T, plus tiic 
number of clock interaipts since the last second. 



Processid Wakeup(pid) 

Processid pid; 

Unblock die specified process if it is delaying using Del ay ( ) and return pid. If the prwess docs not exist or 
is not delaying, return 0. 

int ValidPid(pid) 
Processid pid; 

Return true (nonzero) if pi d is a valid process identifier, otherwise return false. 

Processid WriteProcess3tate(pid, state) 
Processid pid; Processor.state *state; 

Copy die specified process state record into die kernel suite of die process specified by pid and return pid. 

The specified process must be die Invoking process, or awaiting reply from die invoking process. 
WriteProcessState( ) returns 0 if die process does not exist, is not awaiting reply or there is a problem 
with die state record. The kernel checks diat die new suite cannot compromise die integrity or security of die 
kernel 

A pid of 0 specifies die invoking process. A process diat writes its own processor sUite affects only the 
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machine- independent per-process area information kept as part of the state record (sec section 14.5). 



19.2. Other Functions 



Processid Cr9ata(pp1or1ty , function, stacksize) 

short priority; char *funct1on; unsigned stacksize 

Create a new process executing the specified function with the specified priority and stacic size. The new 
process is blocked, waiting for a reply from the creator. The function Ready ( ) should be used to start tlie 
process running. The new process is on the same team as its creator, and inherits tlie creator's standard input, 
output, and error files, and tiie creator's current context (current working directory). 

Create returns the pid of the new process, or zero if a process could not be created. This llmction is 
usually preferable to calling the kernel operation CreateProGes9( ) directly. 



Processid Ready(p1d. nargs, al, .... an) 

Processid pid; unsigned nargs; Unspec al, an; 

Set up the stack of tlic specified process and reply to it, tlius placing it on the ready queue, i'hc values al , 
. . . ♦ an appear as arguments to Uie root function of the new process, while nargs is the number of 
arguments passed. Zero is ixiturned if tliere is a problem, else pi d is returned. 



Destroy(pid) 

Processid. pid; 

Destroy the specified pr(X'css. If the destroyed process was on the same team as tlic invoking process, tlie 
memory allocated to its stack by Create( ) is freed. Warning: Do not invoke Destroy ( ) on a prtKCSs that 
wasnutcrciitedby Create(): useOestroyProcess() in that case. 

SuicideO 

Destroy Uic invoking process and free its stiick. Sulci de() is identical to Oestroy(O), and die siime 
warning applies. 

exit() 

Terminate the execution of the team (i.e., program), after closing all open files. Using the V executive, control 
is returned to the command interpreter. In bare kernel mode, control is returned to die prom monitor. 

abortO 

Abort execution of tlie team by causing an exception in the calling process. 
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The naming section of the library includes a number of functions that provide a convenient interface to 
V-System naming protocol messages. Functions for creating and terminating storage server sessions arc also 
included. 



SystamCode AddContextName(nanie, serverpid, contaxtid) 

char *nanie; Procassld servarpid; Contaxtid contaxtid; 

Add name as a local name for the context specified by ( s a rva rp 1 d , contax ti d and return OK, or a 
standard system reply code if an error i)cciirrcd. This function creates and sends an 
ADD.CONTHXT^N A M K request message to the context prefix server. 



SystamCode AddLogicalNanie(naina, loglcalpid) 
char "^name; Processld loglcalpid; 

Add name as a l(x;al name for tlie default context specified by loglcalpid, and return OK, or a standard 
system reply code if an error (xrcurred. This function creates and sends an ADO^CON rBXT.NAMB request 
message to die context prefix server. 



SystamCode AliasCont8xtName(newname, oldname) 
char *hewnamei, *oldname; 

IDcfinc newname as a local name for die context specified by oldname. oldname is interpreted in ihe 
current context, Returns OK if the name was defined successfully, or a standard system code indicating the 
reason lor failure. 



SystamCode CreateSess1on(host , user, password, sessionname, owner) 
char «host, *user, ''password, *sessionname; 
Processld owner; 

Create. a session on die storage server (usually a Unix server) specified by host, using the given user name 
and password, and define sessionname ;k a local name for die user's home directory on tliis session. If 
owner is nonzero, the session owner is set to be the specified process; otherwise, the invoking process 
becomes tlic session owner. A session is automatically temiinated when its owner no longer exists. 

The given session name is considered die primary name for die session (Uic SHSSION bit is set in its 
descriptor), and its definition should not be removed until die session is terminated. 

CreateSess1on( ) returns OK if successful, else a standard system code indicadng die reason for failure. 



SystemCode Del etoContaxtName( name) 
char *name; 

Remove die definition of die context name name, but do not delete die context it refers to. Return OK if 
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succcssfuK else a system reply code indicating the reason for failure. 

The name is interpreted dirccdy by the context prefix server, not in the current context, since die function is 
ordinarily used only to remove names from die context prefix server's directory. 



Procassid 01 rectToCurrantContaxtC request) 
NameRequest *request; 

Direct a request to die current context, or to die context prefix server if the name begins widi a square braclcet 
('['). The function returns die pid to which die request should be sent, and puts die proper context id into die 
NameRequest messiige. This routine is provided to avoid duplicating die code diat implements die square 
braclcet convention in a large number of functions, request may be of any request type tliat fits die 
standard NameRequest template given in <Vnaming.h>. 



SystamCode 6etContaxtId(naina. serverpld, contextid) 

char *naine; Procassid *sarverp1d; Contextid *contextid; 

Intciprcl Uio given name in tlic current context, and return a corresponding (scrvcipid, contextid) pair in ihc 
locations pt)inted to by sarverpid and contextid. The function returns OK if successful, or a standard 
system error code if an error is detected, such as die given name specifying an object duit is not a context. 



SystemCode GetContaxtNanie(naine. namelan, sarverpid, contextid, nameserver) 
char name[]; unsigned *nainelen; 
Processid *serverp1d; Contextid *context1d: 
Processid nameserver; 

Perform an inverse mapping from the specified (sei-vcrpid, contextid) pair to a character string context name. 
Hie request is sent to Ihc server specified by nameserver. The array name must be *namelen characters 
in length: ^namelen is modified to contain die actual length of die name upon return. *serverp1d and 
•contextid are modified upon return to indicate Uic context in which the name is valid, 
GatContextNameO returns OK if die mapping was successful, or a suindard system error code if a failure 
occurred. 



SystemCode GetF1leName(name. namelen, serverpid, contextid, Instanceld) 
char name[]; unsigned *name1en; 
Processid *serverp1d; Contextid *context1d; 
Instanceld Instanceld; 

Perform an inverse mapping from the specified (serverpid, instanceid) pair to a character string file name. 
I1ic array name must be *name1en characters in length; *name1en is modified to contain die actual length 
of die name upon return, 'serverpid and "contextid arc modified upon return to indicate the context 
in which the name is valid. GetContextName( ) returns OK if Uie mapping was successful, or a standard 
system em)r c(xlc if a failure occurred. 



SystemCode Term1nateSess1on(sess1onname) 
char *sess1onname; 

Terminate die session specified by sesslonname and invalidate tiic name. Return OK on success, else a 
standard system code indicaUng the reason for failure. The session name is interpreted by die local context 
prefix server. The function checks that die SKSSION bit is set in the name's descriptor; if it is not, 
NONl'XlSTHNT.Sl'SSION is returned. 
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Program Execution Functions 



This chapter describes a number of functions relating to program execution. Most of these functions are 
used intcmaliy in the V executive; some of them may also be useflii in user-level programs that need to start 
up other programs as part of tlicir operation. All the functions in this chapter are subject to change. 



21 .1 . Program Execution 



Procdssid LoadProg(argv, concurrent, teamServer. rtMsg» drtMsg, error) 
char *argv[]; int concurrent; Processid teamServer; 
RootMessage •rtMsg, •drtMsg; SystemCode •error; 

LoadProgO interacts with tlie team server to create a new team and load a program image into the new 
team space. It includes palli searching code, which currently always looks for tlie progrum along die default 
padi of 

1. The current context 

2.1110 context "[bin]" 
3. 'ITie context "[public]" 

If all these fail, LoadProg( ) loads the /execute program, which, when started, will attempt to execute tlie 
program on the storage server tliat is providing the current context. 

Tlie array argv contains pointers to tlic character string arguments to be passed to the new team. By 
convention, argv[0] should point to the name of the program. The last clement of Uic array must be a null 
pointer. The concurrent argument spcciilcs whether tlie team is to be "owned" by the pr(x:css executing 
the LoadProg( ) call (if concurrent is zero) or by the team server itself (if it is nonzero). The team server 
destroys any team whose owner ceases to exist: thus, programs to be run "in the background" should be 
tlaggcd as concurrent. The teamServer argument specifics which team server is to create the team. This is 
useful for nmning programs remotely. If teamServer is zero, Uie program is run locally. 

The rtMsg argument holds the root messijgc to be passed to tlic new team. This messiige specifics file 
instiinccs to be used for standard input, output, and error, tlie initial current context, and some other 
information. The fields in the message are described in section 14.4. ITie drtMsg argument is the root 
message to be used to start up the postmortem debugger if a process team on die new team incurs an 
exception. The debugger r(M)t message should specify a real keyboard and display as standard input and 
output, even if the sumdard i/o for the program being loaded is redirected. These root messages are stored by 
the team server. 

ITic function returns Uic pnx:ess id of the new team's r(X)t process, or 0 in case of an error. A standiird 
system code is returned in the location pointed to by error. The new team can be started mnning by 
replying to the pid returned, using the same root message as was passed to LoadProg. 



Processid ExecProg(argv, concurrent, teamServer, rtMsg, drtMsg, error) 
char •argv[]; 1nt concurrent; Processid teamServer; 
RootMessage *rtMsg, *drtMsg; SystemCode *error; 
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Ex9cProg( ) interacts with the team server to create a new team and load a program image into the now 
team space, <\s in LoadProg( ). It tlicn starts the new team running by replying to it. The arguments to 
ExecProg( ) are exactly tlic same as those to LoadProg( ). 



Processid RunProgram(apgv. concurrent. teamServer, error) 
char *argv[]; int concurrent; Processid teamServer; 
RootMessage "rtMsg, 'drtMsg; SystemCode •error; 

RunPrograin( ) performs the same function as ExacProg( ) except that it uses the standard I/O bindings 
to initialize the rtMsg and drtMsg parameter that arc passed in to ExecProg( ). 

Processid LoadNewTeani( teamServer, name, concurrent, argv, 
rtMsg, drtMsg, error) 
Processid teamServer; char *name; int concurrent; char *argv[3; 
RootMessage •rtMsg, *drtMsg; SystemCode •error; 

LoadNewTeam( ) is an internal routine called by LoadProg( ). It docs no paUi searching; the name of the 
flic to load the program image from is given by the name argument The other six arguments are as described 
above, under LoadProg( ), though diey appear in a diflcrent order. 

LoadNewTaam( ) culls Val 1dProgram( ) to check whether the specified file appears to contain a valid 
program image, interacts with die team server to create the new team, and sets up the arguments on the new 
team's stack. 



Processid LoadTeam(f11ename, priority, stackslze, error) 
char •filename; short priority; 
int stacksize; SystemCode 'error; 

Create a new team with tlie specified r(H)t process priority, and load die program contained in the specified 
file into it. The number of bytes specified by stacksize is allocated at the end of tlic team space as a stacic 
area for the team riH)l process unless stacksize is -I, in which case die default 4000 bytes are allocated. If 
the operation is successful, the pid of Uic new team's root process is returned; otherwise 0 is returned. If 
error is not num., ast;mdard system reply code is returned in the location to which it points. 

This function does not request tlie team server to create and load tlie team; it creates the team and performs 
tiic team load itself. It is normally preferable to use one of the other functions described above, ail of which 
make use of Uie team server. 



SystemCode RemoteExecuta(processFile , programnama, argv, mode) 
File •processFileCZ]; char •programnama; 
char •argv[]; unsigned short mode; 

Cause tlie specified program to be executed on the server machine providing the invoking process's current 
context by opening a file in l''liXlr!CUTli nu)de. This function is used by Uic /execute program. 

. Tlie argv parameter is an array of null-terminated strings which are to passed as ai^umcnts to die program. 
The array itself is tcnninatcd by a null pointer, mode should be FRKAI) or FCRHATK. A File sU\icture 
describing a stream from which die program's sumdard output can be read is returned in processFi le[0]. 
If die mode is KCUBA TF,, a File structure describing a writeable stream that is fed into the program's 
standard input is returned in processFi leCl]. RemoteExecute() returns OK if successful, q\sc a 
stcindard system code describing tlie error condition. 

Closing die writeable file passes an end-of-file indication on to die remote program; Closing die readable 
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flic terminates the program. 



21.2. Other Functions 



File ♦Val1dPrografn( filename, error) 

char •filename; SystemCode 'error; 

This ftmction opens the file specified by filename and checks whether it has a valid "magic number," 
marlcing it as an executable V program image. If it is a valid program, Val idProgram( ) returns a pointer 
to a File structure describing the open file: if not, it closes the file again and returns NULL,. A standard system 
code is returned in the location pointed to by error. Hie error code KND_0F.F1LE indicates that the file 
was too short to be a valid program, while BAD^STAl'H indicates that the magic number was invalid. 



SetUpArguments(p1d. argv) 

Processid pid; char *argv[]; 

SetUpArguments( ) is the function called by LoadProg() to set up the arguments on a newly created 
team's stiick. Users will not nonnally need to call it directly. The array argv has the format described under 
LoadProg( ), above. 'Hie pr(x:css id pid specifics the root process of the team whose arguments are to be 
set up. 



ParseLine(start, argv, maxArgs) 

char 'start; char •argvf]; 1nt maxArgs; 

Par sell ne( ) parses a command line into separate words, null terminating each one, and filling in an array 
of pointers to each word. Spaces and tabs arc recognized as word separator. This routine is used by the V 
executive to construct an argv array to pass to LoadProg( ). 

The start argument points to the command line, which should be a null-terminated character string. The 
string is modified by inserting null characters after each word. The array of pointers created is returned in 
argv, which should be defined in the calling program to be of size maxArgs. ParseLi ne( ) terminates the 
array with a null pointer. If Uiere are too many words in Llic command line to fit in Ihc array, only tlie 
Ictlmost maxArgs - 1 words arc returned. 
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— 22 — 
Control of Executives 



IiivStanccs of the V executive, or command interpreter, arc normally created and controlled directly by the 
user interacting witli the sytstem. However, this control is also available to programs through tlic following 
functions: 



Int Cpeat9Exec(ex8Cservep, inserver, InfUe, outsepver, outfUe, 

eppsQPvep, eppfile» namesapvep, context , flags, execpid, 
eppop) 

Ppocassid execsepVQp; 

Ppocdssid Insepvep, outsepvep, eppsepvep; 

Instancald infile, outflTe, eppflla; 

Procassid namasepvep; 

Contextid context; 

shopt flags; 

Ppocossid *execpid: 

SystemCode *8ppop; 

Create an instance of die executive with die specified standard input, standard output, standard error output, 
and context. Kjich of the three standard i/o files is specified by two parameters, the server pid and the 
instimce identifier wiUiin tliat server. This means that all these instances must be opened before Create K-xec 
is called. Context is specified by two parameters, a name server pid and a context identifier within that 
nameserver. The GctCoiitcxtId function will map a context name into such a pair. Kxccservcr is Uic pid of 
die exec server to which the request is being made. 'Hie Flags parameter detentiines which if any of the 
stiiiidard i/o instances are to be owned by the ncwiy created executive: it may be any combination of 
RHLHASli-INPU r.Rlil.KASli- OUTPUT, and RHLI':ASH- KRR. If for example RI':i.HASH-lNPU T is 
specified, die executive will own its sumdard input instance and will release it on termination. 

CreatcKxcc returns an exec Indentificr, a small integer which will be used to refer to this executive in other 
executive control requesLs. In tlie location pointed to by execpid it returns Uie process id of tlie new executive. 
In tlie location pointed to by error it returns a system error code; if Uiis code is not OK, Uie exec identifier and 
execpid are meaningless.. 

WARNING: a server process cannot call CreatcKxcc with a file instance pointing to diat server itself, or the 
server and Uie cxecserver will become deadlocked waiting for each other. A server that needs to do this 
should. create a subproccss to call Crcatcl«'.xcc. 



SystamCode OalateE'xac(axecsepvdP, axacid) 
Ppocassid axacsapvap; 
Int axacid; 

Delete die executive specified by cxccid, along with the program running under it if any. It need not have 
been created by Uiis pr<x:ess: Uiere is no concept of ownership of execs. Note Uiat diis is not die only way 
executives vanish; diey also terminate on end of file on Uic standard input DeietcKxcc will return 
NOT- FOUND if exccid is invalid. 
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System 

Inquire about the state of the specified exec. If successful, it returns a code of OK, and the following 
information: incxccpid tlie process id of tlic exec; in program, the process id of the program running under it, 
if any; in suitus, the status of the exec. Status can be one of 

EXEC - ERl^E Exec is waiting for a command. 

EXEC- LOADING 

exec is in the process of loading a program. 

EXEC -RUNNING 

A program Is running under this exec. In this case and this case only, program returns 
relevant information. 

EXEC- HOLD Exec has been created but not yet started. Hopefully this state should never be observed, 
as it is taken care of within CrcatcExcc. 



SystemCode IC111Prograin(execserver , exadd) 
Processid execserver; 
int exedd; 

Kill the program, if any, running under the. specified exec. Returns OK is successful, NOT-l-OUND if 
execid was invalid. NONKXISTHNT- PROCliSS if tliere was no program running under diatexec. 



SystemCode CheckExecs(axecserver) 
Processid execserver; 

Causes Uic execserver to do a check on ail executives. Any of diem whose standard input server or standard 
output server (but NOT standard error server) has died is destroyed during tlie check. This should be called 
after an action that might have destroyed an i/o server which w<is providing stiindard i/o for one or more 
executives. 
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— 23 — 

Service Registration and Selection Functions 



This chapter describes a number of functions which deal with the globally visible service server; which 
provides registration and selection facilities for globally visible services. A description of the service server 
and the details of how to interact with it are provided in its servers mtinual chapter. This ciiaptcr assumes that 
the reader is familiar with the servers manual chapter and bases the form of its explanations on that 
assumption. All the functions in this chapter arc subject to change. 



23.1. Registration Facilities 



Instanceld R8gisterServer(naineType, namelndex, typelndex, 

ownerPId, desc, descLen, error) 

1nt nameTypo; 
int namelndox; 
int typelndex; 
Processid ownerPid; 
char •dose; 
int descLen; 
SystamCoda *8rror 

RegisterServer registers tlie server descriptor (actually any object descriptor) pointed lo by desc with 
tlie service server. descLan indicates how long die descriptor is in bytes. The owner of the descriptor is 
specified by owner P1d. It is assumed that die descriptor contains both a valid server name and type ilckl, 
whose stiirting indices within die descriptor arc given by namelndex and typelndex. The type field is 
assumed to be a null-terminated string Held. There arc two types of name field allowed: a process id or a 
null-terminated siring field. nameType specifics which type of name field is being used. The allowable 
values for nameType arc defined in die Vservice.h include file, error is used to rclurn a status value 
indicating whether the operation was successful or why it failed. If the operation is successful then 
RegisterServer returns an id number for die server's registration entry. This is used for unregistering the 
server (and possibly other Uiings in die future). 



SystemCode UnregisterServer(serverld) 
Instanceld server Id; 

UnreglsterServer removes a server's registration entry from die service server's database. It takes as 
argument the id number returned from die original RegisterServer operation. 

23.2. Selection Facilities 



Instanceld CreateSe1ectionInstance(serverType. pattern, patternrcn, 

howMany, desc, descLen, error) 

char •serverType; 
char 'pattern; 
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1nt patternFcn; 
1nt howMany; 
chap •desc; 
1nt descLan; 
SystemCode •error; 

Cr9at9Sel6CtionInstanca( ) specifics a set of registered objects to associate with a selection instance 
and returns the first cnti7 of the instance in desc. descLen specifies the maximum size that the descriptor 
returned may be. If the selected descriptor is larger tlian that then only the first descLen bytes arc returned. 
The server type under which selection is to take place is specified by the serverType field, which is a 
null-terminated string. The pattern-matching Hmction to be used is specified by patternFcn. Values that 
this parameter may assume arc defined in the Vsarvica.h include file. The pattern to match against 
registered descriptor entries is pointed to by pattern. The format of tlie pattern as far as this function is 
concerned (its interpretation within the service server will depend on which pattern-matching function is 
specified) is a null-terminated string. howMany specifics whether one or more selections is desired. If only 
one selection is desired then that selection is returned in desc and no selection instance is created. This 
provides a means of circumventing tlic overhead of establishing a full-blown connection for obtaining just 
one selection, error is used to return the status of the operation performed. If the operation is successful 
then CraateSelectionlnstance returns an insuuicc id for the selection instance established. (This 
value is meaningless if howHany equals 1.) 



V-SYSri'M 5.0 Rl-n-RI-NCI- MANUAL 



PROGRAM RNVlRONMI'N'r 



GRAinilCS ITJNCl'lONS 



115 



— 24 — 
Graphics Functions 



The Virtual Graphics Terminal Service (VGTS) allows tlie display of structured graphical objects on a 
workstation mnning the V system. This chapter describes the interface of a client (application) program to 
the VGTS to provide facilities for the creation, destruction, and editing of structured display files (SDl's). 
The user interface to the VGTS is described in the View Manager chapter (chapter 3) of the Commands 
Manual For simple text applications, the VGTS implements the standard I/O protocol. The functions in 
dils chapter are primarily for graphics applications. 



24.1 . Terminology 

'ITic central concept of tlie VGTS is tliut application programs should only have to deal with creating and 
maintaining abstract graphical objects. The dctiiils of viewing these objects are taken care of by die VGTS. 
This is in contrast to traditional graphics systems in which users perfonn tlie operations directly on the screen, 
or on an area of the screen referred to as a viewport or window. Thus tlie VGTS deals with declarative 
information radier than procedural: you describe what the objects are rather than how to draw tliem. 

The following are the types of objects managed by the VGTS: 

SDF A structured display file Is a name space In which symbols and items are defined. F'ach 

item can be given a unique identifier by the client. 

Item Items can be cidier graphical primitives such as rectangles, lines, or text, or symbols, which 

consist of other items. 

Symbol A list of items (primitives or calls to other symbols) used to represent tlie hierarchical 

structure of tlie display file. 

VGT A virtual graphics terminal, can be eiUicr an emulation of an ANSI suuidiird text temiinal, 

or a general graphics terminal which can display an instance of a symbol in some SIW, 

Kvent Graphical input is in terms of events In tlie c(M)rdinate space of some virtual graphics 

terminal. I'or example, a mouse click used to select a displayed object. 

View lk>th applications and users can create views of Virtual Graphics Terminals. A view 

consists of a viewport on some screen of some, workstiition, a window onto some VGT 
giving the world coordinates of the viewed area, and some other viewing parameter. The 
same VGT can appear in several different views, wiUi independent control of all 
parameters. 

Items within an SDF are named with 16 bit identifiers chosen by die application. It is assumed tliat tlie 
application will maintain some higher-level data structures, along with the appropriate mapping to these 
internal item names. Items that will never be referenced can be given item number zero. The item names are 
global to each SDF, but applications may also have several SDFs for dilTerent name spaces. The item 
idcnUfiers are hashed into a symbol table, so there are no constraints on Uicir values. Item numbers can refer 
to both definitions of symbols and their instances. 

For example, a picture of a bicycle might define a symbol for a wheel. 'Hiis definition of the wheel symbol 
is given item number 4. There may then be two instances of item number 4, Uiat arc given item numbers 5 
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and 6. The individual spokes of tlic wheel arc components of symbol number 4, but arc all given item 
number 0. since we will never want to refer to any of them. If it is desired to delete or move any individual 
spoke, then tlic items may be given numbers. 

Each item has the following parameters: 

Item A 16 bit unique (within the SDF) identifier for this object, or zero. 'Phis identifier is 

referenced by the client wiicn performing editing operations. 

Type One of the predefined types described beiow, cid\er a primitive type or one to indicate 

structure. Currently eight bits arc allocated to this. 

TypeData Right bits of type-dependent information, like the stipple pattern number for a filled 

rectangle. Other attributes arc stored here, such as die font index for general text 

Xmin Minimum X coordinate of the bounding box. All coordinates are in "world" coordinates, 

stored as signed 16 bit signed integers. 

Xmax Maximum X coordinate of the bounding box. 

Ymin Minimum Y coordinate of the bounding box. 

Ymax Maximum Y coordinate of the bounding box. 

Pointer [depending on the type, this is cither a pointer to some data like an ASCII text string, or for 

symbol calls, a pointer to llic called symbol. 

Sibling All the component items in a symbol arc linked together via this chain. Normally it should 

not be visible to the client, unless tlie client wants to step through a symbol definition in 
order. 

24.2. SDF Primitive Types 

Some of the meanings of the fields depend on the type of the item. The following are Uie types of items 
that (Mxur in display records in a structured display file: 

SDF.FU .1 i-n.RKCl'A NGLE 

A filled rccUinglc. The TypcDala field determines tlic stipple pattern, or cok)r on the Iris 
system. Refer to Uic Vgts . h include file for Uie available colors. 

SDF.HORI/ONTALJJNR 

Hori/ontal line from (Xmin, Ymin) to (Xmax, Ymin). Ymax is ignored. 

SDK.VHRTICAL,LINE 

Vertical line from (Xmin, Ymin) to (Xmin, Ymax). Xmax is Ignored. 

SDt'^POINT A point, which usually appears as a 2 by 2 pixel square at (Xmin, Ymin)* 

SOK_SIMPLHjrHXr 

A simple text string, which appears at (Xmin.Ymin) as its lower left corner. Currently only 
a single fixed-width font is available. ITie values of Xmax and Ymax need not surround 
the text, but they are used as aids for redrawing, so should correspond roughly to the real 
bounding box. 

SDF.GENERALJJNE 

A generalized line, from (Xmin,Ymin) to (Xmax, Ymax). Note that Xmin etc. arc slightly 
misleading names. The SDF manager actually sorts the endpoints and calculates tlie 
bounding box correctly. 
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SDF.OUTLINE Outline for a selected symbol. Xmin, Xmax, Ymin and Ymax give the box for tlic outline. 

The TypcData field specifics bits to select each of the edges: LeftEdge, RightEdgc, 
TopEdge or liottomEdge. 

SDF^HORIZONTAL.REF 

A horizontal reference line at (Ymin + Ymax)/2. Reference lines consist of a thick line 
with two tick marks at the ends, and some associated text. "ITiey are intended for use in 
computer aided design applications like the Yale layout editor. 

SDF.VERTICAL.REF 

A vertical reference line at (Xmin + Xmax)/2. 

SDF.SKIJ-IORIZ.REF 

A thick (selected) horizontal reference line at (Ymin + Ymax)/2. 

SDF.SEI..VRRT_REF 

A thick (selected) vertical reference line at (Xmin + Xmax)/2. 

SDF^THXT A string of general text, with a lower left corner at (Xmin.Ymin). The Typcl^ata field 
determines Uic font number, Xmax is recalculated from the width information for the 
font. See section 24.6 for an example. 

SDF_RAS'rER A general raster bit-map with a lower left corner at (Xmin,Ymin), and upper right corner at 
(Xmax,Ymax). The TypeData field determines if tlic raster is written widi ones as black or 
white. The pointer field points to the actual biunap, in 16 bit-wide swaths. 

SDF.SPLINE A spline object, of which a special case is a polygon. 'ITic pointer field points to a SPLINE 
structure as defined in the include file <splines.h>. 

'ITierc are a few other types that arc not visible lo the user. For example, symbol definitions and calls are 
represented as items with most of the same attributes. 

Note: ITie following SDF item types are not yet implemented for the SiVfl model 120 framebuffer: 
SOI'7us()'rHXT, SDF2us()RASTKR, SDh7us()G liN ERA L - LI N K and SI31'2us()SPI .1 N E. 



24.3. SDF Manipulation Procedures 

Hie following are the currently defined prtx'cdures used to manipulate the SOI*". When called from C, all 
return values except the actual C expression value arc passed via pointer parameters. If any p()intcr is NUIJ 
no value is returned for tliat parameter. 

short CreateSDFO 

Create a structured display file, and return it. Return -1 if tlic VGTS rims out of resources. This must be 
done before any symbols arc defined. 

short OeleteSOF(sdf ) 
short sdf; 

Return all the items defined in the given SOP* to free storage. Tliis includes ail strings, polygon structures, and 
spline structures associated with items in the SDF. Returns sdf. 

short Def ineSyinboT(sdf , itain, text) 
short sdf. Item; 
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chap 'text; 

Enter symbol into the symbol table, and open it for editing. The sdf is returned from a previous CrcatcSDF 
call. 'Hie text is an optional descriptive name for tlie symbol, used in the hit selection routines for 
disambiguating selections. Returns 1 tern if successful, or zero on some error. 



short EndSymbol(sdf , Item, vgt) 
short sdf. Item, vgt; 

Close the given symbol so no more insertions can be done, and cause the vgt to be redrawn to reflect the nev^r 
SDK. Called at die end of a list of Addltem() and AddCa11() calls defining a symbol, started with 
Def ineSymbolO or Ed1tSymbol(). Returns item if succcssftil. Note Uiat die vgt number is only a 
"hint," because an object can exist in several different VGTs. The client can always-call D1spl ayltem( ) to 
force a vc r to be redrawn. 



short Addltem(sdf, Item, xm1n, xmax, ym1n, ymax, 
typedata, type, string) 
short sdf, item, xmin, xmax, ymin, ymax; 
unsigned char type, typedata; char *str1ng; 

Add an item to tlie currently open symbol. Returns the item name if successful, or zero on errors, string is 
an optional pointer to a text string used only lor text types and reference tines, or special object descriptors for 
rasters and splines. 'I1ic 1 tern number can be /.cro to indicate Uiac die item will never be rcforenccd. 



short AddCa11(sdf , item, xoffset, yoffsat, calledSymbol ) 
short sdf, item, xoffset, yoffset, calledSymbol; 

Add an instance of tlie called symbol to die currently open symbol. The called symbol instance is placed at 
(XolTset,Yoffeet). Returns item if successful, 0 otherwise. 

short OeleteItem(sdf , item) 
short sdf, item; 

Delete an item from Uic currently open symbol dclmilion. 'Hie item name will be removed from the Iiash 
bible. Symbol calls can be deleted just like any other item, but symbol definitions are deleted by the 
IXiicteSymbol function. Again, returns zero on errors, Uie item name if successflil. 



short Inquireltem(sdf , item, xmin, xmax, 

ymin, ymax, typedata, type, string) 
short sdf, item; short ♦xmin, *xmax, 'ymin, *ymax; 
unsigned char *type, *typedata; char 'string; 

Ail parameters except sdf and item are pointers, h'orcach non-null pointer, tlie value of the field for diat 
item is returned. Zero is returned if Uic item could not be Ibund; otherwise item is returned. 



short InquireCall(sdf , item) 
short sdf, item; 

Return Uie iteni name of Uic symbol called by die indicated item. Returns zero if the item is not a call, or 
could not be found. 
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short Changelt8m(sdf , item, xmin, xmax, 

ym1n, ymax, typedata, type, string) 
short sdf, Item, xmin, xmax, ymin, ymax; 
unsigned char type, typedata; char *string; 

Change the parameters of an already existing item. Return zero if the item did not exist, otherwise item. 
This is equivalent to deleting an item and then reinserting it, so the item must be part of the open symbol. 

short EditSymbol(sdf , item) 
short sdf, item; 

Open an already existing symbol definition for modification. This has the effect of calling 
Def ineSymbol ( ) and inserting all the already existing entries to the definitions list The editing process is 
ended in the same way as tlie initial definition process - a call to EndSymbol ( ) . Returns 1 tem if successful, 
0 otherwise. 



short OeleteSymbol (sdf . item) 
short sdf, item; 

l^iiete the definition of a symbol, item must be a symbol definition. Any dangling instances of Uiis symbol 
will remain, but will contain nothing. Returns item if successful, else 0. 

To continue the example of the previous section, to create the bicycle figure we would use code like die 
following: 

short sdf; 

sdf • CpeateSDFO; 

Oef 1 neSymbol ( sdf . 4 . "Wheel " ) : 

Addltefn( sdf ,0. xmin. xmax. ymin. ymax. O.SOF„GENERAL.LINE. NULL); « 

(add the components of the wheel symbol) 

EndSymbol (sdf .4,0) ; ' 

Def ineSymbol (sdf ,3. "Bicycle") ; 
AddCan(sdf .5.xl.ym1n.4); 
AddCa1l(sdf .6,x2.ym1n,4): 
EndSymbol (sdf ,4,0); 



24.4. VGTs and Views 

Once a client has defined some graphical objects, it also needs to provide information on which objects can 
be viewed. Iwery k'iTT' (Virtual Graphics Terminal) is an iteni (usually a staictured symbol) that is associated 
with one or more views, Uiat iictually appear on Uic screen, luich VGT can exist in zero or more views, but 
each view has exactly one VGT associated with it. The "SDI*' NumbcRi" can be thought of as separate object 
dejinUion spaces, while die va i>{ arc object instance spaces. Symbol definitions arc shared between vgts, but 
instances of symbols arc not. 

'ITic VGTS lets a user view objec&s in any VGTs anywhere on die screen in views, Rach view has a zoom 
factor, a window on the world coordinates of some VGT, and screen coordinates which determine its viewport. 
Although die client can create default views, die VGTS user can change Uiem with the window manager, and 
create and destroy more of Uiein. Routines for die client's manipulation of VG'i s and views: 



int CreateV6T(sdf , type, topltem, string) 
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Short sdt; int type; short topltom; char •string; 

Create a vgt, return the VGT number, and put the indicated item as the top-level item in the VGT. The type 
can be some combination of Tl'Y, GRAPHICS, and ZOOM ABLE The Pads created by making TVY vgts 
can presently only be manipulated by tlic VGTS or tlirough the I/O protocol interface (Sec the description of 
OpenPad in section 24.7.2). If the ZOOMABLE bit is set, the view zooming factor can be changed by tlic 
user. The top Item can be zero to Indicate a blank vgt. Returns negative on errors. 



int DeleteVGT(vgt) 
short vgt; 

Destroy the given VGT. All the views of the vgt will also be destroyed. 

D1splayItQni(sdf , topltem, vgt) 
short sdf , topltem; Int vgt; 

Change the top-level item in a VGT. ITic new item is displayed in every view that contains the vgt. 

int Def au1tView( vgt, width, height, wXmin, wYmin, 
zoom, showGrid, pWidth, pHeight) 
short vgt, width, height. wXmin, wYmin, zoom, showgrid; 
short 'pWidth, 'pHeight; 

Create a view of tlie given vgt, with the user determining die position on tlie screen with the graphics input 
device. Hie width and height parameters give the initial size of the view if they arc positive. Zero (or 
negative) values indicate that the user should dctenninc tlie size with die mouse at run-time. See \hc View 
Manager section of die commands manual (chapter 3) for more infbnnation about the user interface. 

If die pWidth and pHeight pointers are non-NUKL, then tlie shorts which dicy point to receive the 
selected width and height. wXmin and wYmin arc die world coordinates lo map to Uic left and bottom edges 
of die viewport. The zoom factor is the power of two to multiply world coordinates to get screen courdin(Ucs. 
The y.oom factor may be negative, to denote Uiat a view is zoomed out. If showGrid is non-zero a grid of 
points every 16 pixels is displayed in the window. Returns negative on ermr. 



24.5. Graphical and Character Input 

'Hie VGTS maintains an event queue for each instance, and die vgts associated with the given file instance, 
'llie mode bits of die instance give die kind of events diat will be queued. The following functions arc 
available to handle die event queues: 



LISTTYPE FindSe1ectedObJect(sdf , x, y, vgt, searchType) 
short sdf , X, y, vgt; 
char searchlype; 

Return a list of items that arc at or near die selected location within die VGT. Along with each item is a set of 
edges, to indicate diat the hit was near one or more edges of die object. 'Hie searchType selects one of 
several modes of hit detection, as given in die <Vgts.h> include file. Usually die consuuit value All will be 
used. The return type LISTI'YPE is also defined in diis file. 
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typedef struct MinElement 
{ 

.short item; 
short edgeset; 
struct MinElemeni *next; 
} MINREC, -MINPTR; 

typedef struct Listlnfo 
{ 

MINPTR Header; 
short NufflOfElements; 
} LISTTYPE; 



Short popup(menu) 

PopUpEntry inenu[]; 

Provide a "Pop-Up" menu. The menu argument points to an array of PopUpRntry structures, each of which 
is a string and a code. Hic array is terminated by a NULL string. The code of the menu item selected by the 
user is returned, if the user cliclcs outside die menu a negative value is returned. 

typedef struct 
{ 

char •string: /• String to display. */ 

unsigned char menuNumber ; /* Number returned if entry selected. */ 
} PopUpEntry; 



24.6. Defining and Using Fonts 



short Def 1n9Font(nani9, flleName) 
char •name, *fileNain«; 

Defines a font to be used in subsequent SDI*'Jl'HX'r items. 'I'he name is a pointer to a string giving the name 
of the font, for example, "HclvcticalOIV. 'I'lie font is read by the VG'l'S rn)m the file with the paUinamc 
given iis the second argument. The f HeName argument can be null to indicate a read from the standard 
place. The fontlD returned by this call is used as the TypcOata field of the Addltem call for these character. 
A negative return value indicates an error. I'or example, 

short roman - Def 1neFont( "TimesRomanlZ" , NULL): 
Addltem(sdf. 0. x. x, y, y. roman. SDF_TEXT. "Hello") 

will diiHJlay die string "Hello" in the Times Roman font at 12 point size, at Uie position (x,y) on die screen. 



24.7. Using the VGTS 

Tlie constants for mouse search types, vciT usjigc types, etc. are found in the include file Vgts . h. The stub 
routines are available in the default V library, so just including the option -V on your cc68 command line for 
linking should work. l>o NO I* include the -1 Vgts option on your command line. 

Use -TVgts on your cc command line for transparently running programs on a Unix system. Use 
-I/usr/sun/1nclude to get the file Vgts.h. This package uses an escape sequence which can be used 
through PUP Telnet, IP Telnet, or with the remote command execution facility of tlie executive. Please 
contact the auUior for the details of diis protocol if you wish to implement it on some other operating systems. 
'Ilicrc already arc efforts underway for using Uiis protocol from TOPS-20 assembler programs (e.g. SUDS) 
and InterLisp. 
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24.7.1. Cooking Your Pads 

The following mode bits arc maintained for eacii pad to indicate the amount of rawness of the 1/0: 

CRJnput Change the CR (return) character to LF (UNIX newline) on input This is for the benefit of 

UNIX programs which expect '\n' as a line terminator. 

LF.Output Change LF to CR-LF on output. That is, every line- feed operation is preceded by a return. 

Echo Echo input characters. This bit should be off for programs which can also run on the kernel 

console device^ 

LineBuffcr Wait for a line of input before returning. The user interface to the line editing feature is 
described in section 2.7.1. 

PagcOutput Block the writer each time a pad fills up with output, and wait for the user to issue a 
command which unblocks the pad. The user interface to the PagcOutput feature is 
described in section 3.3. 11iis bit is "on" by default 

PageOutputHnablc 

When turned on in a ModifyPud request, Uiis bit causes the new value of die PagcOutput 
bit to bo assigned to a user-controlled, "sticky" cnable/disiible bit. The PagcOutputl-nable 
bit should only be used by "privileged" programs (such as executives) as a means Lo allow 
the user to "permancndy" disable paged output mode. A QUERY_KILH request will 
return tlie actual value of the PageOutputHnablc biL 

DiscardOutput When set, this bit causes all output to a pad to be ignored. It is automatically set when die 
user types 'q' to a pad diat is blocked at the end of a page In PagcOutput mode. It is 
automatically cleared whenever the VGTS sends input to a program diat is reading from 
the pad. 'Hie bit may also be cleared "manually" via ModifyPad. Application programs 
should call ModifyPad to clear diis bit before sending a prompt to a pad, to insure that the 
prompt is not discarded along wiUi any previous output Uiat was discarded at die user's 
request 

Report Transition Report every change of buttons on die graphical input device as a significant event. 
ReportClick Report events only \yhen all Uic buttons have been released on the graphical input device. 
NoCursor I To not display a cursor in Uic indicated pad. 

'llie default when pads are created, or commands arc initially nm by die executive, is for all Uic keyboard bits 
to be on, and Uic mouse bits to be off. 

24.7.2. Other Interface Routines 

The following routines to communicate with die VGTS via die I/O protix:ol interface are in die V library: 



File *OpenPad( name , 1 1nes , columns , error) 
char *name; 
short lines, columns; 
SystemCode 'error; 

Retumsa file descriptor for a new pad, error is a pointer to die reply code, normally OK, A null pointer is 
returned on an error. Note Uiat Uic file descriptor returned is open for writing. If you want to read from it, 
you must use Open File to create another file descriptor with the same filescrver and fileid. 
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SelectPad(fne) 

FUe •file? 

Causes tlie indicated file to be selected for input, and brought to the top. 

Mod1tyPad(file,mode) 
File -fne; 
1nt mode; 

Sets the Cooked mode of the file, mode is some combination of the bits described in the previous subsection. 

1nt QueryPad(f 1le) 
FUe •filej 

Returns the Cooked mode of the file, some combination of the bits described in the previous subsection. 

-fnt QueryPadS1ze(f 1l8,p11nas,pco1s) 
File -fne; 

short •pllnes, •pools; 

Gets the number of rows and columns of the specified pad, storing Uicm in tlic shorts pointed to by pi i nes 
and pools. Vhc value rctui-ncd is the same as for the preceding function. 

GetTTYO 

PuLs the terminal in raw mode. The Unix version of this routine does the appropriate Unix operation if 
standard input is a tty device, otherwise it sends the proper code for the remote execution facility. 

« 

ResetTTYO 

Restores the mode before die last GetTTY(). Runs under UNIX as well, checking standard input properly. 

GdtGr aph i cs £ ven t ( f i 1 e , px , py , pbuttons ) 
File •file; 

short •px, *py, *pbuttons; 

Waits for a graphical event in tlie indicated VGT, and returns the world X and Y coordinates in the shorts 
pointed to by px and py. liie stiUe of tlic buttons is returned in (he short pointed to by pbuttons. Use the 
file pointer std1n to get events in VGTs that were created with CraateVGTO. 



Sys temCode GetGraph 1 csS tatus ( f 11 e , px , py .pbuttons ) 
File •file; 

short •px, •py, •pbuttons; 

Returns after any motion the world X and Y coordinates in tlic shorts pointed to by px and py. The state of 
the buttons is returned in tlic short pointed to by pbuttons. The value returned will be KOK if die graphics 
cursor is not within a view of the given VGT. 

GetEvent(f i 1 e , px , py , pbuttons . cbuf ) 
File •file; 
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short 'px, *py, *pbuttons; 
char •cbuf; 

Waits for any event in the indicated VGT, and returns the world X and Y coordinates in the shorts pointed to 
by px and py, and the buttons in the siiort pointed to by pbuttons if the event is graphical, or else returns 
the characters in the buffer pointed to by cbuf. 'ITic return value is zero for a graphical event and the byte 
count for keyboard events. 



RedrawPad(f He) 

Waits until the indicated pad- is redrawn. 



PadF1ndPo1nt(vgt,n1ines.x,y.pl1ne,pco1 ) 
short vgt. nllnes, x, y; 
short •pUne, •pcol; 

Converts a set of world coordinates in x and y into a line and column position within a pad. Currently the 
vgt parameter is unused, and tlic number of lines must be specified in n 1 1 nes. 



24.8. Example Program 

'ITie following program can be run eitlicr under Unix or under the V system executive. 'Hie #if def VAX 
directives allow the programmer to conditionally compile code for one environment or the other. It first 
creates an SDK and VGT. then displays 100 random objects of various kinds. 

/• 

* test.c > a test of th« remote VQTS Implementation 

* Bin Nowickl September 1982 
•/ 

It Include <Vgts.h> 
» Include <Vio.h> 



ft define Objects 100 /* number of objects */ 

short sdf. vgt: 

Quito 
C 

Oe1eteVGT(vgt,l): 
Oe1eteSOF(sdf ): 
Re8etTTY(); 
exItO: 

} 



ma1n( ) 
C 

Int 1: 
short Item; 
long start, end; 



V-SYSri'M 5.0 UFPHRI-NCl- MANUAL 



PROGRAM r-NVIRONMUNT 



UXAMPLIi PROGRAM 125 



» Ifdef VAX 

piHntf ("Remote VGTS test progpam\r»") ; 
» else VAX 

printf("V6TS test programXn") ; 
it endlf VAX 

f f 1ush(st(Jout) ; 

GetTTYO: 

sdf ■ CreateSOFO ; 

Def ineSyfflbol ( sdf, 1. "test" ); 

Addltem( sdf. 2, 4. 40, 4, 60, MM. SDF.FILLED.RECTANGLE, NULL ); 
EndSymbol( sdf, 1, 0 ); 

vgt * CreateVGT(3df . GRAPHICS+ZOOMABLE. 1. "random objects" ): 
OefauUV1ew(vgt, SCO, 320, 0. 0. 0. 0. 0, 0); 

t1me(&start) : 

for (i-12; i<Objects: 1++ ) 
{ 

short X ■ Randoni( -2, ISS); 
short y ■ Randoni( -10, 169); 
short top ■ y > Random( 6, 100 ); 
short right - x Random( 4, 120 ): 
short layer > Randoni( NM, NG ); 



Ed1tSymbol(sdf , 1): 
0e1ateltem( sdf. i-10): 
switch (Randoin(l, 9) ) 

{ ' . 
ease 1: 

Addltem( sdf. 1. x. right, y. top, layer, 
SOF_FILUED_R£CTANGLE. MULL ); 

break; 



case 2: 

Addltem( sdf. i. x. x+1000. y, y+16. 0, SDF.SIMPLE.TEXT. 

"Here Is some simple text" ); 
break; 



case 3: 

Addltem( sdf. i. x, right, y, y+1. 0. 

SDF_HORIZONTAL_LINE. MULL ); 

break ; 



case 4: 

Addltem( sdf, 1, x, x+1, y. top, 0, 
SDF.VERTICAL.LIME, MULL ); 

break; 



case 5: 

Addlteiii( sdf, i. x, right, y. top. 0, 
SOF.GENERAL^LINE. MULL ); 

break: 
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case 6: 

Addltein( sdf, 1, x, right, top. y, 0, 
SOF.GENERAL.LINE, MULL ); 

break: 

} 

EndSynibo1( sdf, 1. vgt ): 

> 

t1(ne(&end) : 

if (end""Start) and ■ start+t; 

printf(''%d objects in %d seconds, or %d objects/sacond\r\n". 

Objects, end-start, Objects/(end-start)); 
printf("Oonel\r\n"); 
Quito: 



Randoin( first, last ) 
{ 

/* 

* generates a random number 

* between "first" and "last" inclusive. 
•/ 

int value ■ rand()/2: 
value X- (last - first + I): 
value +■ first; 
return(value) ; 
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— 25 — 

Fields: Using a Pad as a Menu 



These routines allow you to set up a table of fields in a pad. They can be selected with the mouse, so that 
you can have a menu. ITic advantages over the sumdard pop-up menu are that you can have more choices, 
you can display more information with each choice, and the menu is always there. 

With each field, you can associate a value, which can be displayed and edited. 

The menu is an array of F 1 e 1 ds. These arc defined in <f 1 el ds . h>. Each Field consists of: 
typedef struct 
{ 

short row; /• field's row number in pad */ 

short col; /• leftmost character of field ♦/ 

short width; /• width of field */ 

long *value; 
int (*proc)(); 

char *format; /• format in which to display *value */ 

} Field; 

row and col indicate where in the pad the field begins. (row= 1 and coi= 1 is the top Icfl: comer of the pad.) 
width is the length of die field in characters. OnJy one-line fields arc supported, ppoc is not used by the 
package itself! The intended useage is: 

field » 6etField( . . .) ; 

if (field) (*field->proc))(f ield->value) ; 
or perhaps: 

if (field) (•field->proc))(f ield) ; 
format is discussed below. 



25.1. Formats 

format is a format like those used by printf and scanf . TogcUicr with the value, it determines the 
string to be displayed in die Held. Hiis string must be a least w1 dth characters long. It is a /.ero-temiinaied C 
(asciz) string. Formats are of die form: 

prefix [conversion] suffix 

Here prefix and suffix is constant text which is displayed. If a X is to be displayed, it must be written as %%. 
'] he following utility routine will do a string copy analogous to strncpy, except Uiat %s arc automatically 
copied: 



char * StrToForraat(f ♦ s, n) 

char 'f; /• destination string buffer where Ts arc to be doubled •/ 
chap •a; /• source string •/ 
Int nj /• count - buffer size •/ 

The optional conversion describes how val ue is to bo displayed/ read. Its form is: 
VH[Weldwidih][,preci5ion][\]c 
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Here the % indicates die beginning of the conversion specification. The conversion type letter c marks the end 
of the conversion specification.' 'I'he format is exactly as used by printf, except that there may be a data 
length specification \. If value is a short • rather tlian a int *, X must be given as h. If tiie vaT ue is a 
doubl e • rather tlian a f 1 oat *, X must be 1, or the conversion type letter c must be capitalized. 

When fields are displayed, spplntf is used to do the conversion. The length specification X is only used 
to dereference value (except for fields where the conversion type letter is s); it is stripped from the format 
before being passed to sprlntf . 

On input to fields, only the length specification X and the type code c are passed to sscanf . If the type 
code is e or g, it is changed to f . 



25.2. The Field Table as a Menu: Selecting an Action 



Field * QetF1eld(nienu, menuLength, buttons, pad) 
Field *inenu; 
int menuLength; 
short buttons; 

File 'pad; /* output pad •/ 

if button !■ 0, it is assumed tliat Uie mouse is down on procedure entry. GetField returns when the 
button state changes: if it changes to non-zero. GetField fails by returning zero. If button 0, 
GetField will first wait for an event. (It will fail unless it is a mouse button being pressed down.) 

As long as the user keeps tlic mouse button down, display the selected field (if any) in inverse video. When 
the user releases the button, return the last selected Field, or if none, return 0. 

Vhc menu is terminated by the first negative row field, or when the menuLength count is exhausted. 



25.3. Displaying Fields 



PutField(buffer, field) 

char "buffer; /• destination siring buffer •/ 
Field 'field; /• source fonnut and value • / 

More or less like sprintf( buffer , f ield->forraat, 'f ield->value). 

DisplayFields(menu, menuLength, pad) 
Field *menu; 

int menuLength; /* see GetField function */ 

File *pad; /* output pad where fields are to be written */ 

Display in die pad all tlie string fields, at Uie positions given by the row and col components. 

. I'he width components are ignored. 'ITiis allows convenient display of material which the user cannot 
select ("write-protected" fields) either by using fields with wi dth <■ 0 or by having a str i ng longer tlian 
die width. 



V-SYSTl'M 5.0 RI'l-l-UI-NCH MANUAL 



PROGRAM ENVIRONMIiNT 



USI'R INPUT TO FIELDS 



129 



25.4. User Input to Fields 

Ed1tFl9ld(fl0ld, stuff, out. 1n) 

Field *field: /* field whose * value is to be edited •/ 

1 nt stuff ; /• 0: old text should be cleared: I: stuff into editor ♦/ 

File •out, *1n; /* input and output sides of pad to use ♦/ 

Move the cursor to the conversion part of the field. If stuff is 0, tiic old value is cleared from the screen; 
if it is 1, tivs old value is placed in the line editing buffer. Enter line-edit mode, and wait for the user to type 
in a line. If the user types tG, abort, redisplay old value and return -1. Else parse the line using 
f 1eld->forinat. If this succeeds, update *f ield->value, returning i, else 0. In any case, redisplay 
things correctly. 

Ed1tStdFld(f1eld) 

Equivalent to Ed1tFie1d(f1eld, 1, stdout, std1n) 



R8adStdF1d(f1e1d) 

Equivalentto EditF1e1d(f 1e1d, 0; stdout, std1n) 



25.5. An Example 

/* This Is a program which adds up Integers, optionally scaled */ 

^Include <std1o.h> 

^include <f1e1ds.h> 

double Scale » 1.0, Total - 0.0; 

Int Value '0; 

Quito { ... cleanup actions ... ; exlt(-l):} 

NewVa1ue(f) 
Field ♦f: 

{ 

If (ReadStdFld(f ) »■ 1) 
. Total +- Value * Scale; 

} 

Fields Menuf] ■ 
{ 

/♦ VAL (defined In fields. h) coerces pointers and values to (Int *) •/ 
{1, 41. 10. VAL aScale. EdItStdFld. "Scale; XS 
(1. 1. lii. VAL &Value. NewValue, "New value; X-Sd**}. 
{2, 1, 0, VAL SiTotal, 0. "Total: %G. "}, 

(8, 1, 8, 0. Quit. "—Quit—"}. 

LASTFIELO /* defined In fields. h •/ 

>; 



ma1n( ) 

{ Field *f1eld; 
while (1) 
{ 

putc('L' & 31. stdout); /* write FormFeed to clear screen 
DisplayFields(Menu, 999. stdout): 
field - GetF1eld(Menu, 999, 0, stdout): 
If (field) (•(f1eld->proc)) (field); 

> 

} 
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Since the screen is updated every time ticre, we do not have to worry about garbage being left bcliind when 
tlie field becomes shorter. However, I have shown two solutions which can be used when this is not desired: 
In the Va1 ua field, we make sure die field doesn't become shorter, by left justification if needed. This loses if 
we want to output punctuation after the value, as in the Total field. In diis case, we can make surc that we 
output enough trailing spaces to erase the garbage. 



25.6. Limitations 
No facilities yet for arrays. 
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SUN PROM MonitorEmulator Traps 



'ITic emulator trap interface flinctions in the V C library are listed below. These are extremely dependent 
on the version of the SUN workstation PROM monitor being used. The use of these functions should be 
avoided if at all possible; none of them are present in the Unix C library. For more information see the Sun 
User's Guide, Note tliat not all tlie traps mentioned Uiere are available under die V kernel, since processes 
always run in user state. 

int eint.getconf 1g() 

Returns the current value of the "configuration register." 

1nt 9mt_g9tmems1ze() 

Returns the size of the on-board RAM in bytes. 

chap emt„getchar() 

lJusy-wait input from tlie console. Will not work unless the kernel console device is closed to prevent it from 
"stealing" tlic characters. 

Int erat_putchap(c) 
char c; 

Busy-wait output to the console. 
Int emt_t1cks<) 

Returns tlic number of milliseconds since die monitor wius last booted. Incremented at each memory refresh. 
Int enit„vers1on() 

Returns ttic version number of die prom monitor. 

1nt fbinoda(newinode) 
1nt newmode; 

Qucries/scis die frame buffer mode. 

satecho(f Tag) 
int flag; 

Controls whether characters read using emt^ge tchar ( ) arc echoed. 
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Miscellaneous Functions 



27.1 . Time Manipulation Functions 

The time-related fiinctions in tlic V C library arc described below. A few of ilicm arc not present in the 
Unix C library. 



stime(), t1nie(), ftimeO 

These are Unix system calls and arc implemented here with simple library functions wliich emulate tiic Unix 
functions by performing the appropriate V kernel operations S#tTiine( ) and GatTime( ). They have the 
same interface and functionality as in Unix; however, f tiniQ( ) has die time/one hardwired as Facillc Time, 
since the V-System provides no time zone information. 



ct1ffle(), local tinie( ) , gmtimeO. asct1me(), tlmezoneO 

These arc idendcal to the Unix library functions. 

sleep(sac6nds) 

unsigned seconds; 

The invoking process is suspended from execution for the specified number of seconds. 'ITie actual time may 
be considerably longer fJian that sped lied if the process is not the highest priority ready process when its sleep 
time expires. sleep() is not sensitive to Wakeup()'s. Use tlic V system call Delay() for a 
WakeupO'abie suspension. 



unsigned GetRemoteTiffleO 

Returns tlie time according to die TIMH^SHRVHR in seconds since January 1, 1970, GMT. Returns /.cro if it 
fails, e.g., no dme server responded. Currently die Unix servers act as time servers. 

27.2. Strings 

The string-related functions in die V-System C library arc described below. 

27.2.1 . Unix String Functions 

The following functions arc idendcal to die functions of the s<ime name provided by Unix. See the Unix 
Programmer's Manual for dcx:umentation. 

atof() atoi() atol() crypt () 

ecvt() gcvt() index() r1ndex() 

stPcatO strncatO strcinp() stpncmp() 

strcpyO strncpyO strlen 
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27.2.2. Verex String Functions 

ITicrc is also another set of string manipulation functions wiiich were ported from Verex. These include the 
following: 

int Any(c, string) 

char c; char •string; 

Determine whether there is any occurence of the byte c in the string string, and return true (nonzero) if so. 
else false (zero). . 

char *Concat(d9St. si, s2, s3) 
char •dest. 'si. 'sZ, *sZi 

Concatenate the strings si, s2, and $3, store the result in dest, and return dest. dest must have enough 
room to store tiic resulting string. If any of si, s2, s3 are null pointers, die remaining arguments are 
ignored. 

Int Convert_nuni(str1ng, dellm, base) 

char *str1ng; char **del1ni; unsigned base; 

Parse the given string to extract a number of base base and return its value. If base is zero, the initial 
character of tlic string determines the base, as follows 

# Base 2 
0 (zero) Base 8 
$ Base 16 
otherwise Base 10 

Upon return, *del1in is modified to contain a pointer to die delimiter that terminated the number. 

char •Copy_str( string) 
char 'string; 

Copy die given siring into a newly allocated region of memory and return a pointer to the copy. 'ITie new 
region is allocated using mal 1oc( ) and may dius be freed using f ree( ) when ihe copy is no longer needed. 

Int Equa1(sl, s2) 
char 'si. •s2; 

Compare tlic strings si and s2. Return true (nonzero) if the strings are equal, else false (zero). Strings are 
considered to he equal if and only if Uiey are of equal length (up to die terminating null byte) and each 
corresponding byte is liic same. 

Int Hex_value(c) 
char c; 

Return die value of c, interpreted as a hex digit. Return -1 if c is not a hex digit 
char •l.ower(strlng) 
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Char •string; 

Convert all alphabetic characters in str 1 ng to lower case and return str 1 ng. 

unsigned Nun_str(str1ng) 
char *str1ng; 

Return true (nonzero) if string is a null string (i.e„ of length zero), else return false (zero). 

char •Sh1ft«left(str1ng, chars) 
char ^strings unsigned chars; 

Delete the leftmost chars characters of stri ng by shifting the remaining characters to the left, and return 
string, str 1 ng must be at least chars characters long, but Uiis condition is not checked. 

unsigned Slze(string) 
char *str1ngi 

Return die number of characters in die given string, i.c., die index of die null byte that terminates die string. 

char •Upper(string)" 
char •string; 

Convert all alphabetic characters in string to uppercase and return string. 
27.3. Other Functions 

qsort(base. nel , width, compare) 

char •base; 1nt nel, width; int (•compare)() ; 

ImplcmenLs die quici^sort algorithm, base is a pointer to die base of tlie data; nel is the number of 
elements: width is die width of an element in bytes: and compare is a function to compare two elements. 
The functitjn compare must return an integer less than, equal to, or greater than zero, if the first argument is 
less Uian, equal to, or greater Uian the second, respectively. 

setjmp(env) 

jmp^buf env; 

1ongJmp(env, value) 

Jmp.buf env; int value; 

set jmp() saves die stack environment in env, so diat a later call to 1ongJmp( ) will act like a return was 
made from die function which contained die call to set jmp( ), with return value val ue. 

char •ErrorString(error) 
SystemCode error; 

Returns a pointer to a string describing the system request or reply code error, in human readable terms. 
Use Uiis in error messages instead of prinUng the numeric value of die code. 
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PrintErrop(9PPOP, msg) 

SystemCoda eppop; chap *msg; 

Prints tlic string msg and an explanation of the SystcmCodc 9PPop on the standard error file. 
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— 28 — 
Servers Overview 



All system services other than those implemented by tlie Iccrnel are provided by sending a inessagc to one of 
the system server processes. This manual describes the protocol for requesting these services, including the 
fomat of the request message, the format of the reply message, the possible values for the message fields, and 
the process that handles the request. This information is generally not required by application programmere 
because the protocol is implemented in a library of standard functions that provide system services via simple 
function calls. The library is described in the V-System program environment manual. More sophisticated 
use of the system requires tlie more det<iiicd information in this manual. 

This chapter describes some general message format standards used In communicating with servers. The 
next two chapters give dciails of two standard protocols, the V-System I/O Protocol <ind V-Systcm Naming 
Protocol. The remaining chapiei'S give the detailsof tlie particular scrvei'S, describing which oftlicse prolt)ct)ls 
they implement, additional server-specific request types tlicy provide, and the server-specific semantics of the 
services and requests each implements. . 



28.1 . Message Format Conventions 

System server protix:ols obey several system-wide conventions. Tlie first short word of every request 
message contains a request code indicating the service requested. The first short word of every reply message 
contains a code indicating the successful completion of Uic request execution or the reason that die request 
was not executed nomially. A requesting process can assume that tiie request has been completely executed 
when the reply message is received with a successful reply code (alUiough in cases such as disk write-behind 
til is may not be strictly true). 



28.2. Standard System Request Codes 

K'lch syslctn request is allocated a unique request code to be placed in the first word of the request messiige 
when requesting that service. 'Hie request codes obey Uie me&sage format conventions imi)osed by tlie kernel, 
as described for Send( ) in the V envirojiment manual. The manifest constiint definitions for these request 
codes are defined in the stiindard C include file <Vcnviron.h>. 



28.3. Standard System Reply Codes 

'ITic reply code returned in a message from a server is normally one of the following sumdard system 
replies: 

OK Operation successful. 

ABORTEID An operation was aborted. For example, a network connection that has been aborted 
returns tliis code. 

BAD^ADDRIJSS Request contains an invalid memory address. 

BAD.ARGS Request contains field(s) with illegal or inconsistent values. 

BAD.BLOCK_NO 
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"ITie block number specified in an I/O request docs not specify an existing block. If the file 
instance has attribute STREAM, the block number docs not specify tiic block which is 
sequentially next in reading or writing. 

BAD.BUFFER A buffer specified in the request lies (perhaps partially) outside the client's address space, 

BAD.nrrE.COUNT 

The byte count is larger (or smaller) dian diat supported by the server. On a file instance 
without the MULTl.lJl.OCK attribute, this is returned if tiic number of bytes requested to 
read or write is greater tlian the block size. 

BADJ>R0CESS_PR10RITY 

The request specified an illegal value for a process priority. 

BAD.STATE Request invalid at this time. 

BUSY llic server cannot satisfy the request at this time, probably because tlie requested resources 

are allocated to anodier client. 

CU RR BNT.CONTl-XT.I N V A 1 .1 D 

Normally only returned by library routines, not servers. 'ITie routine has detected that the 
current context of Uic culling process is invalid, probably because its process-id component 
refers to a nonexistent process: 

DEVICK.HRROR 

File or device-dependent error has occurred. 

DUPUCATK.NAMK 

The request attempted to assign the same name to two different objects. 

EN13_0K_Fll .E Attempt to read beyond file boundaries. 

ILLHGAL^REQUHST 

Invalid request code. The request was probably sent to the wrong type of server, t»ne which 
could not perform tliat function. 

INTHRNAL.ERROR 

Hie server detected an inconsistency In its own stiite. This error code may indicate a bug in 
Uie server. 

INVALID.CONTEXT 

'I1ic request contained a context identifier (sec chapter 30) that was invalid. 

INVAUD.FILEJI5 

'I1ic request contained an invalid file instance identifier. 

INVALID.MODK 

'Hie mode specified ns part of a CREATH.INSTANCE request is not valid. 

lO.BREAK Returned from interactive files. 

KERNEL.T1ME0UT 

A timeout occured in Uie kernel when trying to send to a remote process, lliis error differs 
from NONF^ISTHNT.PROCHSS in Uiat the sending kernel did not receive a negative 
acknowledgement from the remote kernel, but for most purposes it can be handled in the 
same way. 'Hiis error code is only generated by tlic kernel, but may be passed on by other 
servers. 

MOID! LNOT.SUPPORTED 
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The mode specified as part of a CREATE.INSTANCE request is not supported by diis 
server. " 

NO_MEMORY The server was not able to obtain enougli memory to satisfy tiic request. 

NO.PDS The server was not able to create a process or team needed to satisfy die request. 

NO.PERMISSION 

Some kind of restricted operation was attempted. 

NO^SERVERJ^ESOURCES 

The server has (temporarily) inadequate resources to satisfy the request. 

NONEXISTENT.PROCHSS 

The request was sent or forwarded to a nonexistent process, or a nonexistent process was 
specified in the request. This error code is only generated by the Icernel, but may be passed 
on by other servers. 

NONKXISTFNT.SESSION 

The request referred to a session (sec ciiapter 36) which does not exist, or to an object 
whicii is not a session. 

NO'LAWAITINGRHPLY 

The process specified in a request was not awaiting reply from the client. 

NOT.KOUND The object named in the request was not found. 

Nar.RRADABLE 

Specified file instance does not have the attribute READABLE which is required for the 
requc:sted opcradon. 

NO'LWRn'EABLE 

Specified file instance does not have the attribute WRITEABI.E which is required for the 
requested operation. 

POWERJ'AILURE 

Operation was unsucessfui due to a power failure. 

REQUKSr.NOr.SUPI'ORTHD 

The server recognizes the request, but docs not support it. 

REl'RY Client should repeat request 

SERVER_NO'rjUiSlK)NDING 

'ITic server failed to receive a response from another server specified in tlie request 

TIMEOUT An attempt to satisfy the request failed because of a timeout. Usually applied to network 
connections. 

'Hie EprorStPlng() function described in the V i'.nvironment manual will return a character string 
version of many of the system reply and request codes. The string form is much more informative than 
printing Uic codes in numeric form. 
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— 29 — 

The V-System 1/0 Protocol 



A Standard input/output protocol is defined in V to provide transfer of data between processes in a uniform 
fashion. Using tliis protocol, a dieni process views and accesses data managed by a server process as a file. A 
file is a "view" of tlic data assix:iatcd with an object or activity managed by a server. An object viewed as a 
file is a sequence of variable-size records or blocks. 

To operate on an object viewing it as a file, it is necessary to create an instance of tliat file. The protocol is 
objevi'based in die sense that it is defined in terms of operations on a object, the file instance. Kile instance 
operations include: crcadng a file instance, querying a file instance, setting tlie file instance owner, reading, 
writing, and releasing file instances. There arc also operations for setting a prompt string and break process 
associated with a file instiincc which are restricted to interactive file instances. A server tliat supports tiiis 
protocol is called an I/O server or file instiince server. (The term "file server" might be more appropriate if it 
did not have a dlH^erent established meaning in the research literature on distributed systems). 

A file instance is created by a server in response to a client request, which specifies the file, i.e. die object or 
data and the particular view and usage required. Conceptually, a file instance is an object which is created at 
the time of die client's CREATK^INSTANCH request and (possibly) initialized to contain tlic same data as 
an existing, pennanent file. When the instance is rele<ised by the client, the data contiiincd in the instance is 
atomically written back to the corresponding pennanent file. For st)me servers (for example, the internetwork 
server), however, there is no permanent file corresponding to an instance, while for others (for example, die 
device server), there is cflcctivcly no distinction between die instance and die pennanent file - chnngcs in the 
instance are immediately reflected in die underlying file or I/O device. The current implementation of some 
storage servers (e.g., the V Unix server) also causes changes in an instance to be immediately reflected in the 
underlying file. 

A file instance is uniquely identiflcd by die server process identifier and die ins/ance identifier rciurned by 
die CRHATH^INSTAMCH request. Hie creating process is made tlie owner of the file instance. The lifetime 
of the file instance and the validity of die instimce identifier does not exceed llint of the owner of the file 
instance. ITieowner ofa file instance can be changed by die SKT.INS TANCI^^OWNI IR request. 

'Hie reply mcssiige to a CRHATH_INSTANCK or QUHRY^INSTANCK request specifics the server, file 
instance idendfier, block length in bytes, file type, last block (written) in die file instance, number of bytes in 
die last block, and die next block to read. 

'ITie file type indicates die operations that may be performed on tlie file instance as well as tlie scjnantics of 
diesc operations. These types are defined in die include file <Vio.h>; file types are specified as some 
comblnadon of die following attributes. 

RI'AIMBLK RIvAD.lNSTANCK operations arc allowed on the file insUincc. 

WRITHABLE WRITK.INSTANCK operations are allowed on die file instance. 

APPBND.ONLY WRrFEJNSTANCE operations are only effecUvc to bytes in die file instance beyond the 
last byte associated with the instance at the dmc it was created. 

STREAM All reading and writing is stricdy sequential. The first READ.INSTANCH operation must 

specify die bkxrk number returned as nextblock in the reply to the CRHATH.INS'l'ANCE 
request This next block number to read is incremented after each RHAD^INSTANCE 
operation. Its current value is returned by a QUERY.INSTANCE. A server must store 
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the last block read and allow it to be read again, to provide duplicate suppression on 
requests. 

Similarly, cacti WRITE INSTANCE operation must specify the block number returned as 
lasiblock by CREATEJNSTANCE or QUERY.INSTANCE. ITiis block number is 
incremented after every write operation. A server must ignore requests to rewrite the last 
block written, returning a reply code of OK, U) provide duplicate suppression on requests, 

A file instance without the STREAM attribute stores its associated datii for non-sequential 
("random'.') access. That is, on a non-stream file, for any n, block n may be read or written 
at any dme, and reading block n will return the same data as was last written to block /i. 

Since each file models a single sequence of data blocks, objects which provide bidirectional 
communication, such as serial lines or network connections, are most appropriately 
modeled as a pair of file instances, one a READABLE STREAM, the other a 
WRITEAHI-E STREAM, Some servers may allow both instances to be created by a single 
CRHA TE^INSTANCE request*^ 

FIXEDJ.ENGTH 

The file inst^lnce is fixed in length. The length is specified by the last block and last byte 
returned from a create or query instance request. Otherwise tlic file instance grows to 
accommodate Uie data written or else tlie length of the file instiince is not known (as in the 
case of terminal input). 

VARJABLH.BLOCK 

BliKks shorter than tlie full block si/.e may be returned in response to read operations other 
than due to end-of-file or other exception conditions. For example, input frames from a 
communication line may differ in length under nonnal conditions. 

With a file instance that is VARIABLE.BLOCK, WRrn^:ABLE, and not STREAM, 
blocks that are written with less than a full block size number of bytes return exactly the 
amount written when read subsequently. 

MULTl^BLOCK Read and write operations are allowed diat specify a number of bytes larger than tlie block 
si/c. 

INTERACTTIVI^ 'Hie file instiuicc is a text line-oriented input stream on which a prompt can be set using the 
Sirrj^ROMKI' request and a break process can be defined using the 
Sin'_BUEAKJ*ROCESS request. It also has tlie connotation of supplying interactively 
(human) generated inpuL 

Not ail of the possible combinations of attributes yield a useful file type. The file instance types supported 
by ciich server arc documented with each server. 

A client must specify a mode of usage for the file instance when creating it. Hie mode is one of FREAD, 
FCREA TE, I'MODIF'Y and F'AFPEND. The modes of usage have the following semantics. 

l''Rl"iAD No write operations arc to be performed, only reads. 

FCREATE Any data previously associated with die described file is to be ignored and a new file 



A few existing scrvcis bend this rule by assigning Uic same instance id to Uie input and output streams, even thougti biocic number n 
of the input stream. Ls unrelated to block numt)er n of tlie output stream. Strictly speaking, this behavior is in violation of the protocol, 
and we plan (o change these servers cvcnlualty. A single STRivMVt (hat is both RI!Al')AiU,i: and WRrriiAUI.M would have to return 
ihc data written (o block n if block n Ls btcr read back. 'lliLs type of Hie might be used to model a Unix-like pipe, but in fact, the 
V-Systcm pipe server (.sec chapter 33) takes a dincretii approsich, creating a separate instance for each end of the pipe, with the 
connection between ihcni invi.sibic to the protocol. 
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instance is to be created. Write operations arc permitted; read operations arc also 
permitted if die file instance has type attribute RHADAiiLE. 

FAPPEND Data previously associated witti tlic described file remain unchanged. Write operations are 
permitted only to append data to die existing data. 

FMODIFY Existing data is to be modified and possibly appended to. Both read and write operations 
arc required. This is only supported on file instances that arc not STREAM. 

A server creates a file instance of a suitable type for die specified usage mode if it can. For example, the 
storage server provides file instances with type attributes READABLE, FlXED_UvNGTH and 
MULTLBLOCK in response to a CREA'IEJNSTANCE request specifying FRKAD usage mode. 

One of diree modifiers may be used on die mode field of a CREATK^INSTANCE request 
FDIRECTORY Indicates that the given name specifics a context directory. See section 30.7. 

FEXECUTE Specifies diat die given file is to be executed as a program on the storage server machine. 

The mode must be FREAD or FCREATK. Respectively, one or two file instances are 
returned, which allow reading from the program's si*mdard output, and optionally (in 
FCRKATE mode) wridng into its standard input When two instances are created, die 
filcid of the second (readable) file instance is obtained by adding 1 to die filcid of die 
writeablc instance (which is returned in die reply message). This mode modifier need not 
be supported by ail storage servers. 

FSE^SION Specifies diat a session is to be created on die server machine, using die (null-separated) 
user name and password passed in the filename field of die CREATE_INSTANCE 
request 'ITie file server pid returned is die process id of die session. Releasing die file 
instance id returned will teniiinate die session. The session will also be tcmiinalcd after 
the death of die instance owner. This mode modifier is only supported by storage servers 
diat use the concept of "session." See section 36. 

'ITie following subsartions give the format of die request message and die format of die reply, plus a 
description of the semantics for each operation in the protocol. These message formats are defined in the C 
include file <Vioprotocol.h>. • 



29.1 . CREATE INSTANCE 



rcqucstcode CREATE.INSTANCE 

nienamcindcx 'Hie index of die first byte in die filename to use in die name mapping. 

type Type of file to create an instance of. This is used, for example, to specify die device to the 

device server and protocol to die internet server. 

filcmodc l>?sircd iisiigc mode indicating l-'RI-AD, l'CRI'.ATK. FAPI'E.ND or PMODII'Y, plus 

optionally FDIRIiCrORY. FllXECU TH, orbSESSlON. 

unspecified Server-dependent in formation specifying die file to be created. 

contextid Specifies die context within die server in which die filename is to be interpreted. (Sec 

section 30.2.) 

filename Pointer to a byte array containing die symbolic name of die server or . file, 

filenamclen Number of bytes in filename, not including die terminating null byte. 
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rcplycode Standard system reply. If the reply code is not OK, the file instance was not created and 

the remainder of the reply is not defined. 

fileid File instance idendfler. This is the number used in subsequent operations on the file. 

fileservcr Process identifier of the server managing tliis file. This is not necessarily the same as the id 

to which Uic request was sent 

blocksizc Maximum size in bytes of a block. 

flletype Type attributes of ttie file instance as described at the beginning of this section. 

filehtstblock Index of the last block in the file or of the last block written to tlie file instance if It is a 
STREAM file. Indexing is 0-origin. 

filelastbytes Number of bytes in the last block. For file instances which arc not WRITHAIif-E and not 
FIXEDJ.ENGTH, this field and the Jilelasiblock field should return the maximum 
unsigned integer. 

filenextblock Number of tlic next block tliat can be read if this file is a READABLH STRHAM. 



Tlie CRF.ATH_INSTANCK request is issued cither directly to the server or sent via a name server process. 
In Uic former case, the use of the fields of Uic request is server-dependent and is documented for each server. 
In the latter case, the unspecified field is not filled in by the client- Hic name server maps the syinbolic name 
to a server and a server-dependent description of the file and then forwards the request to the appropriate 
server. An 1/0 server may not use the filename, Jilenameien, and filenameindex fields if it docs not support 
symbolic naming. 

'Hie fleid and y//«<?rv<?r uniquely identify the file instance created. The file instiincc exists until released or 
until the requesting process ceases to exist 



29.2. QUERY INSTANCE 



requestcodc. 
fileid 



QUKRYJNSTANCK 
File instance identifier. 



replycodc A standard system reply. If the reply code is not OK, the file instance was not queried and 

Uie remainder of the reply is not defined. 

fileid File instiincc identifier, siimc as the request for compatibility with the reply to the 

CRI^ATUJNS TANCK request. 

filescrver Server process identifier. 

blocksize 'ITie maximum size in bytes of a block. 

filetype Type attributes of the file instance as described at the beginning of tlie section. 

filelastblock Index of the last block in tiie file or the last block written to the file instance if it is a 
STREAM file. Indexing is 0-origin. 



filelastbytes 



11ic number of bytes in tlie last block. 
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filcncxtblock Number of tlic next block tliat can be read if tlie file is a READAIM^E STREAM. 



In response to a QUERY_TNSTANCE request message, the server queries the file instance specified by 
filcid for the parameters supplied in the reply message. The reply message has the same fonnat and semantics 
as the reply to a CRJ"!ATE^INSTANCK request except for tlic reply code. For example, a reply code of 
NO'LPOUND to a CREATH_IN STANCE request indicates that tlie file specified does not exist, while a 
reply code of INVALID.FILeLiD to a QUERY.INSTANCE request indicates the file instance docs not 
exist. 



29.3. RELEASE INSTANCE 



rcqucstcode RELEASEJNSTANCE 
filcid File Instance identifier 

relcascmodc Server-dependent action to perfonn when releasing the instiince. 'Hiis field is set to zero 
on a normal close. 



replycodc A standard system reply code. 



• In response to a RELEASK.INSTANCE request, tlic server invalidates the insumce identifier, reclaims 
server resources dedicated to the instance and possibly perfonns some server-dependent function with die file 
instimce data. A releasemoUe o( 0 indicates nonniil completion of the use of the file instance. For example, in 
Uic case of the printer server, the file instance dalii is printed. In the case of the storage server, the datii 
atomically replaces tlic previous version of tlie stored file data. A non-zero release mode causes the data to be 
discarded. 

A server may release a file in.stiincc with a non-/.cn) release mode if it detects that the process (hat created 
the instiincc no longer exists. A server should maximize the time before reusing a file instance identifier. 



29.4. READ INSTANCE 



rcqucstcode 
filcid 

blocknumbcr 
buffcrptr 

bytccounc 



replycodc. 
filcid 

shortbuffer 



REAO.INSTANCE 
File instance identifier 

Index of the block in the file from which the read is to begia. 

Address of the data buffer in which the data is to be moved if more tlian 
IO.MSG_UUl'1''FR bytes are read. That is, lO.MSG.BUFh'ER Is the maxiinuin number 
of data bytes that fit in tlic message. 

Number of bytes to be read. 



Standard vsystem reply code. 
Same as in request 

lO.MSG.BUFFER bytes containing the data bytes read if less than or equal to 
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10_MSG_RUFFHR bytes, 
by tecount Number of bytes read. 



In response to a READ.INSTANCF. request, the server transfers up to byiecounl bytes from tlie file 
instance starting at tlic block numbered blocknumber. If the number of bytes read is less than the number 
requested, the reply code indicates the reason. If the file instiincc has the type attribute VARIABLH_BLOCK 
and the block being read was not the flill block size specified for the file instance, this case is not an error, and 
the reply may be OK, or KND.OF.FILE if the last block was read. Note that a client may ignore the reply 
code if die returned byte count is equal to tiic requested byte count, so servers should set the byte count to 
zero on error conditions. 

If the number of bytes read is less than or equal to IO_MSG_BUFFKR, the data read is contained in the 
reply message starting at shortbuffer. If it is greater Uian lO.MSG.BUFFKR, the data read is transferred into 
the space of the requesting process starting at the address bujferptr. 

If the flic instance has the type attribute STRHAM, the bi(x:Ic number specified must be the next block to 
rend for this instance, which is incremented after the read. Reads always start ut the beginning of tlic 
specified block. ITic values of bylcs read tliat were not explicitly written are undefined. The number of bytes 
requested must be less than or equal to tlie block si/e unless the file instance has tlie type attribute 
MULTLBLOCK. 

29.5. WRITE INSTANCE 



requestcodc WRITK.INSTANCE, or WRrrHSHORT.INSTANCE if bytecount is less than or equal to 
lO.MSG.BUFreR. 

filcid File instance identifier. 

blocknumber Index of the block in the file instiincc at which the write is to begin. 

shortbuffer Data bytes to be written if less than or equal to lO.MSG^UUFFHR. 

bufferptr Address of tlic data buffer if no more Uian IO_MSG_BUl'^'F-R bytes arc being written. 

Otherwise, this field may be overwritten by tlie data bytes. 

by tecount Number of bytes to be written. 



rcplycodc Standard system reply code, 

bytecount Number of bytes written. 



In response to a WRITH.INSTANCH or WRITI'SI IOR IllNSTANCK request, tlie server transfers up to 
bylecount bytes to llic file instiincc storting at the bl(x:k numbered blocknumber. If Uie number of bytes 
written is less than Uie number requested, tlie reply code indicates tlie reason. As witli RKAD_ IN STANCH, a 
client may ignore the reply code if Uie returned byte count is equal to Uie requested byte count, so servers 
should set the byte count to zero on error conditions. 

If Uie number of bytes to write is less Uian or equal tt) IO.MSG_nUFFHR, the data is assumed to be 
contained in Uie request message stiirting at sliortbiiffcr. If it is greater Uian I0_MSG_BU1-'FHR, the daui is 
transferred from Uie space of Uie requesting process starUng at Uie address bujfcrpfr. Writes nlways start at the 
beginning of Uie specified block. Note Uiat Uic separate request code WR1TF51 lORT^INSTANClv is used 
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when tlic data is contained in the message only to be consistent with tlie kernel message foiTnat conventions, 
'nicrc is no RRADSHORT INSTANCE needed because the data is passed back in the reply. TTiat is, 
WRITE.INS'rANCB specifies that segment access is being passed while WRl'rESHORT.lNSl ANCE 
specifies no segment access. 

If the file instance has type attribute STREAM, Uie block number specified must be one greater than the 
last block in this file instance, which is incremented after die write. The number of bytes to write must be less 
than or equal to d\c block size unless the file instance has the type attribute MULTI_liLOCK. 



29.6. SET INSTANCE OWNER 



requcsccode SEILINSTANCE.OWNER 

filcid File instance identifier 

instanceowncr Process identifier of new file instimce owner. 



replycodc Standard system reply code. 



hi response to a Sli r„INSTANCI{.OWNER request, the server sets the file instance owner process to that 
specified by instanceowner. The requesting process must be the current owner of tlic file instance. The inidal 
owner of a file insutncc is the process that created tlic instance. 



29.7. SET BREAK PROCESS 



requestcodc SHT„UREAKJ^ROCHSS 
filcid File instance identifier 

breakpixKcss l>roccjijs to be "broken" when next break generated on diis file instiuice, 

replycodc Standard system reply code. 

In response to a SITr„UREAKJ^ROCF^S request, Uie server sets the break process a.ssociatcd with die file 
instance to the process specified by breakprocess. When a break is generated on this file (the IO_liRF*AK 
reply returned to any outstanding read operations), the server issues a l>stroy Process kernel operation on the 
specified process. 

This request is only supported on file instances with type attribute INTERACl'IVIi. 
29.8. SET PROMPT 



requestcodc SET^PROMIT 
filcid File instance identifier 
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promptstring Prompt string, which must be Ic&s than lO.MSG.BUFFHR bytes long. 



rcplycode 



Standard system' reply code. 



In response to a SKT.PROMFr request, the server sets the prompt string output previous to every read 
operation to tliat specified. This request is only supported on file instances with type attribute 
INTERACTIVE. 



29.9. QUERY FILE and NQUERY RLE 



rcqucstcode 
filcid 



QUERY.FILE 

File instance identifier 



requestcodc NQUKRY.FILE 

namcindcx 'I*hc index of tlie first byte in the file name to use in tlic name mapping, 

unspecified Up to the last three 32-bit words in the message, 

namccontextid Context in which die name is to be interpreted, 

nameptr Pointer to a memory segment containing the file name, 

nameiength I .ength of the segment in bytes. 



replycodc Standard system reply code, 

unspecified Server dependent information. 



In response lo a 0UI''RY.I''I1 or NOUI'!RY_l'IIJ{ request, tlic server returns server spocillc information 
about die file or file instiuice. h'or example, die VG'I S returns the "c(H)king" bils, and die internet server 
returns ci)nnection information. A QUHRYJ'11,1*. request specifies die file using an instance identifier, while 
a NQUHRY.FILH request uses a charactcr-sU'ing name. Both types of request return die same information. 



29.10. MODIFY FILE and NMODIFY FILE 



requestcodc IVIOi:)IFY.I'ILR 

fileid File instance identifier 

unspecified Server-dependent information. 

requestcodc NMODIFY.FILE 

namcindcx 'Hie index of die first byte in the file name to use in the name mapping. 
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unspecified 



namcptr 



namelength 



namecontcxtid 



Scrvci-dcpcndcnt information. Up to the last throe 32-bit words in the message. 
Context in which the name is to be interpreted. 
Pointer to a memory segment containing the file name. 
Ixngth of the segment in bytes. 



replycodc 



Standard system reply code. 



The MODIFT^FILK and NMODIFY^FILE requests are supported by some servers to modify some 
attributes of the file or file instance. For example, tlie VGTS uses MODIFY.FII.E to turn echoing on and 
off. • 

A M0DIFY_F1LR request specifics which file is to be modified by passing an instance idendfier, while an 
NMODiFY.FlLK request passes a character string name. 
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— 30 — 

The V-System Naming Protocol 



A number of V-System services use character string names to specify the objects to be operated on, and 
many standard message types include space for such a name, liixamplcs include tlie CRHATE.INSTANCE 
request and several other requests described above as part of the I/O J'rotocol. 

Name mapping in ttie V-System is performed by a collection of cooperating server processes rather than a 
single, monolithic "name server." The V-System Naming Protocol consists of a unifonii format for request 
messages that contain symbolic names, and a small set of request types which must be handled spcciiiily by 
any server that implements the protocol. 'Hie protocol also specifies conventions for forwarding partially- 
interpreted requests from one server to another. 



30.1. Character String Names 

Syntacdcally, a character string name (CSnatnc) is a sequence of zero or more bytes, of a specified length or 
else terminated by a null byte. Operationally, a character string name is a byte string as above that is used to 
specify an object relative to a server that Ciin interpret tlie name. There is no universal limit on the length of 
character string names,, Two CSnames arc equal if and only if they are bytc-wisc identical and equal in length 
(where a null in the name tiikcs precedence over tiic length specification). 

Although CSnames may contain arbitrary bytes, they are generally specified or chosen by die client (as 
opposed to the server) and are usually human-readable ASCII strings. 

The term character string name handling server (CSNH server) refers to any server that pcrfonns cliaractcr 
string name mapping, regardless of what else it does. The tenn CSname request describes any request 
containing a character string name tliat must be mapped in order to pcrfomi tlic requested operation. 

30.2. Contexts and Context Ids 

In general, tlie interpretation of a siring name depends on the context in which the name is used. I 'ormally, 
a context is a set of (name, object)-tuples. A context can have an arbitrary set of members in theory. In tlie 
V-System, the context of a name includes (1) Uie server to which Uie name is to be sent, and (2) the place 
within that server's naming hierarchy where interpretiition is to begin, or more generally, the context within 
the server. A server is specified by its process id, while a context within a server is specified by a context 
identifier. A context identifier is a 32-bit identifier assigned by tlic server. Thus in general, a context is 
specified by a (server-pid, context-id) pair. 

'ITiis definition does not specify deUiiled semantics for contexts, leaving it lo individual servei's. This is 
similar to Uie I/O protocol where, for example, the semantics of writing to a file instance is not specified but is 
scrvcr-dcpcndenL 'ITius, each name server must specify the semantics of its contexts. Kor example, while a 
file server may implement a purely hierarchical name space and only implement contexts diat modify Uic 
semantics of so-called relative padinames, a internetwork server may implement contexts that correspond to 
different networks, or sets of hosts talking particular protocols, etc. 

A context-id has tlie same lifetime as the server. Thus, aft:er a context-id is acquired by a client, diere is no 
need (and no way) to release it when the client is finished using it. A context-id identifies Uie context itself, 
not an "instance'* of the context 'J herefore, we have made context-ids relatively long (32 bits). 
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Basically, character string name mapping is stincturcd as three levels: server, context and CSnamc. 
However, a CSname may be structured hierarchically, as in the case of a filesystem pathname. 'I'hc naming 
protocol is independent of tiiis structure, though usually each component in a hierarchical name will be tlie 
character string name of a context in which the rest of the name is interpreted. 

It is expected that, given a character string name, a server and a context id, the interpretation of that 
character string name is fully specified independent of die operation requested. 



30.3. WeiL-Known Context Ids 

We require that context-id 0 (called DEFAUIT.CONTFXO represent a valid context on every CSNH 
server. In general, DFiFAUl.T.CONTHXT sliould be a reasonable default for clients diat are not sure which 
context within a server a name should be mapped in, but do know die server. For example, a server that 
provides access to a Unix file system should map DKFAULT.CONTEXT to the root directory (known as 
'7"). A server tliat provides only one context should number it 0. 

Other small context identifiers (less than 16, say) are reserved for use as "well-known" contexts. There is a 
need for some servers to publish certain context ids, similar to Dl'FAUL'r.CON'rh'X'r, and some servers 
may provide ccruiin contexts which have special properties. Currently defined well-known contexts include 

DltFAUL'r.CON'n-XT 

As described above. 

PUBLIC.CONTKXT 

hlolds publicailyavailnblc V program.s on storage servers. 

LOGIN.CONTHX'r 

'.ITie home directory of the owner of a session, on storage servers tliat implement tlie 
concept of a session. 

ANY.CONTKXT 

A special value used with Uie GKrj'Il.H.NAMK and GFILCONTHXT.NAMF 
operations. When returned by one of these operations, it indicates the name is an 
"absolute" name, valid in any context on the given server. When passed in tlie contcxtid 
Held of a GHT^CON'rHXT^NAMF request, it acts its a wild card, i.e., Ijie server receiving 
llic request may return tlie name of any context on tlie server spcciiled in the request. 

30.4. Name Request Format 

AH V-Systcm request messages that contain CSnamcs arc built on a common skeleton, defined as Uic 
Namcllequest suticture in tlie standard header file <Vnaming.h>. 

requestcode Any valid request code that grants read access to a segment. 

nameindcx 'Hie byte offset of tlic name, within tlic segment specified by Uie last two long words of tlie 
message. 

unspecified Request-specific information, up to tiic last three long words in the message, 

namccontcxtid A 32-bit idendfier for the context in which this name is to be interpreted, 

nameptr Pointer to the segment containing the symbolic name, 

namelength Length of die segment containing the name. 
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The reply is not specified by this protocol because it is generally dependent on tlie operation requested. 

The niune need not be first in the segment but is considered to start at the byte offset specified by 
nameindex. If the name is not last in the segment, it must be terminated by a null. A CSNH server may reject 
a request if the total segment size is too long for it to handle. 



30.5. Name Parsing and Forwarding 

A CSNH server follows the following algorithm in handling a request containing a CSname. 

If Uic server does not provide pointers to contexts in other servers as part of its name space, it may interpret 
the name in any way it chooses. 

Otherwise, tlic server begins by looking at the name itself, not the request code. Since this request may 
have been directed to another server (to which it will eventually be forwarded by this algoridim), tlie request 
code is irrelevant at tliis point 

Names are ordinarily interpreted left-to-right, if the server implements hierarchical naming. The server 
initializes the variable CurretuConlext to tlic context id specified in the request. As each component of the 
name is parsed, it is looked up in the current context. If tlie name specifics a context, CunenK'ontext is 
updated.. If the new context is implemented by some other server, the nameindex field in the request message 
is updated to point to the first character of the name not yet parsed, the namccontextid field is set to 
CiurentContext, and the request is forwarded to the server that implements the context. 

A server with a fiat name space may ignore the contextid field of requests, but it must set tliis field when 
forwarding requests to other servers. 



30.6. Standard CSNH Server Requests 

'Hiere are seyeral standard CSNH requests, which- should be implemented by all CSNH servers, and others 
which need only be implemented by context prefix servers (sec chapter 42), but may be implemented by 
others as well. All of Uic request and reply formats described below are subsets of the ContcxtRcquest 
stnictirre defined in tlie st<mdard system header file <Vnaming.h>. 

30.6.1 . GET CONTEXT ID 



requestcode GKl'_CONTKX'r_ID 

nameindex 'I1ic byte offset of the name, within the segment .specified by the last two long words of the 



message. 



namccontextid 



Context in which to interpret tlie given name. 
Pointer to ilw segment containing tlie symbolic name. 
Length of the segment containing the name. 



nameptr 



namelength 



contextid 



rcplycodc 
scrvcrpid 



Standard system reply code. 

The serverpid component of the named context 

llie contextid component of Uie named context 
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cntrytypc Optional, scrvcr-spccific type ui formation. 

instanccid File instance id associated with tlic context, if any. Server-specific. 

otherinfo Optional, server-specific information. 

Given a CSnamc tliat names a context, this request returns a (scrvcrpid, contcxtid) pair which identifies tlie 
same context 

30.6.2. GET CONTEXT NAME 



requestcodc GKr.CONI'HXT.NAME 

servcrpid The scrvcrpid component of the context for which a name is to be found. 

contcxtid The contcxtid component of the context. 

namcptr Pointer to a buffer in which Uie name is to be returned. 

namelcngth Si/eof tlic buffer. 



replycodc Standard system reply code. 

servcrpid 'lUc scrvcrpid component of the context in which tiic returned name is valid, 

contcxtid 'I1ic contcxtid component of the context in which the returned munc is valid, 

namcptr The value provided is returned unchanged, 

namelcngth Length of tlie returned name. 



Returns a CSnamc corresponding to the specified (scrvcrpid, contcxtid) pair, if one is known to the server 
receiving Uic request, plus the server and contcxt-id required to fully qualify the CSnamc. The context-id 
returned will be ANY.CONTHXT. if possible, and Uie server will ordinarily be the one to which the request 
was sent 

Since tlie inverse mapping from (scrvcrpid, contcxtid) to CSnamc is not well-defined in general, a server 
may sometimes fail to satisfy Uiis request despite its best cffoits. Also, tlierc may be many possible choices for 
the name that is to be returned. Servers should attempt to return a name Uiai is as int^briTiativc to a human 
user as possible. 

30.6.3. GET FILE NAME 



requestcodc GJn'J'TLH_NAME 

instanccid A file instance id for the file whose name is desired, 

namcptr Pointer to a buffer in which the name may be returned, 

namelcngth Sizcoftiic buffer. 
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rcplycodc Standard system reply code. 

servcrpid The serverpid component of the context in which the returned name is valid, 

contcxtid The contextid component of the context in which the returned name is valid, 

nameptr Tlie value provided is returned unchanged, 

namelength Length of the returned name. 



Returns a CSname for the file associated with the specified file instance, plus the server and context-id 
required to fxilly qualify tlie file name. The context-id returned will be ANY^CONTEXT, if possible, and the 
server will ordinarily be the one to which the request was sent 

30.6.4. ADO CONTEXT NAME 



rcqucstcodc Ai:)D,CONTEXT_NAMK 

namcindcx The byte offset of die name, within the segment specified by the last two long words of the 
message. 

serverpid Server pid to assign to name, 

contcxtid Context id to assign to name, 

cntrytype Server-specific type information, 

instanceid ' Instance id assixiated with context, if any. 

olhcrinfo Server-specific. 

•namecontextid Context in which to interpret (or define) tlie given name, 

nameptr Pointer to die segment contiiining die symbolic name, 

namelength Length of die segment containing the name. 



replycodc 



Standard system reply code. 



The ADD.CONTl'-XT.NAMH operation defines a new CSname to refer to an existing context. The 
existing context is specified in die (serverpid, contcxtid) fields of the request. The specified CSname is 
interpreted according to die naming protocol, in die context specified by namccotuextid^ until the mapping 
aigoridim reaches a context in which die remainder of die name is not defined, at which point it is aclded to 
diat context 

This operation need only be implemented by context prefix servers, but of course all CSNH servere must be 
able to forward it in accordance with die naming prot(x:oi. 

30.6.5. DELETE CONTEXT NAME 



rcqucstcodc DRLirrE.CONTFXr.NAME - . 

namcindcx The byte offset of die name, within die segment specified by die last two long words of die 
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message. 



namccontcxtid 



namclength 



namcptr 



Context in which to interpret the given name. 
Pointer to the segment containing the symbolic name. 
Length of the segment containing the name. 



contcxtid 



entry type 



replycode 
serverpid 



othcrinfo 



instanceid 



Standard system reply code 

The serverpid component of the name's fomier value. 

The contextid component of the name's former value. 

Server-specific type information formerly associated with the name. 

File insuince idciitincr formerly associated with the name, if any. 

Server-specific information formerly associated with the name. 



Delete tiic specified context name, making it no longer meaningful. 'ITic context associated with this name 
is not deleted. This operation need only be implemented by context prefix servers, but of course all CSNH 
servers must be able to forward it in accordance with tlie naming protocol. 

30.7. Context Directories and Object Descriptors 

Kach context consists of a set of (name, objcct)-tuplcs and is implemented by a server process. 'Hie 
discussion so far has concentrated on perfonning operations on specific objects and the protocol for 
specifying a particular object. However, an important aspect of system operation is supporting query 
operations about t)bjccts or sets of objects. A simple example is Uiat of listing the names of all objects in a 
given context In general, one may wish to list a variety of information about objects in a context, perhaps 
ignoring some of tlK objects based on Uieir properties. 

Bich CSNH server implements one or more coniext directories of objects that it manages. A context 
directory appears as a file of records, with each record specifying an object in Uie associated context. A 
directory file is accessed using tlie I/O protocol with Uie CKI*.A'ri^_INS'rANCl'- request specifying the name 
of Uie context to be used. Hie l-'DIRKCrOKY bit is set in tlie mode field of such a request. A client can then 
use the st^indard I/O routines to read die contents of the directory and derive the information required. The 
selection of Uie information required is done by the client, not the server. Hie client may also be able to 
modify some or all of the fields of a directory record by writing it, using the stiindard I/O proKxiol. A server 
is not obligated to make all fields presented in a directory modifiable. If a client attempts to change a 
non-modifiable field, Uiat field should be Icll unaltered, but any other changes indicated in the request should 
be carried out 

'Hie FDlRFCrOKY bit is primarily for tlic benefit of Verex-like file systems, which pennit each node in 
Uie naming hierarchy to be (in Unix terms) both a file and a directory. It discriminates between access to tlie 
data content of such a node, and Uie context directory associated with it. Also, servers Uiat do not implement 
character sting naming at all can use {his bit to disUnguish between requests to access one of the objects Uicy 
manage and requests to read Uieir context directory. 

Hach record in a directory starts with a descriptor- type field Uiat specifics die format of the record describing 
Uie object For space economy, Uiis field is an identifier Uiat specifies a description of Uie record fomiat 
stored elsewhere in a system dat^tbiisc of such formats. (The standard fonnats and descriptor type idenUfiers 
are defined in the header file.<Vdirectory.h>.) Applications can read a directory and exti:nct the required 
information by referring to Uie descriptor-type field and Uiesc fomiat descriptions, even when a directory 
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contains heterogeneous records. 

A similar query activity involves accessing ttic descriptor of a single object. For efficiency and consistency, 
this is supported by a separate RHA1D_DGSCRI1^"0R function on tlie object (as opposed to being subsumed 
by the context directory fiicility), which returns the same record as found in tlie context diicctory. A 
corresponding WRri'K._bESCRlPrOR operation is available for modifying an object's descriptor. 

nicrc is no implication that a server need store information about objects as it is presented in a context 
directory. For inst^incc, the Unix file system stores the names of files separate from tlicir descriptors with the 
association provided by so-called "i-nodc numbers." A context directory enti7 in this case is fabricated 
dynamically by replacing the i-nodc number in each record by its descriptor. 

The standard descriptor reading and writing operations arc described below. The message formats used are 
described by tlic DescriptorRequest and DescriptorReply structures defined in <Vdirectory.h>. 



30.7.1. READ DESCRIPTOR and NREAD DESCRIPTOR 



requestcodc RHAD^DHSCRIKI'OR or NKH,AI)_l)KSCRlPrOR 

nameindex 'Hie byte offset of the name, wiihin the segment specified by the last two long words of the 
mcssiigc (NRRAD.DHSCRIPIOR only). 

filcid File instance id of tlie file whose descriptor is to be read (REAI)j:)RSCR J PI'OR only). 

dataindex The byte offset from the start of tlic specified segment where the returned descriptor is to 

be placed. 

namccontextid 'Hie context id of tlie context in which tlie given name is to be interpreted 
(NRHAD.Dl'SCRIFl'OR only). 

scgmentptr Pointer U) a buffer which contains the object name (for NRHAD^DHSCRIFI OR), and in 
which tlic descriptor is to be returned. 

scgmentlcn I .engtli of the buffer. 



rcplycodc Standard system reply code, 

dataindex Returned unchanged, 

scgmentptr Returned unchanged, 

scgmentlcn Returned unchanged. 

'Hiesc request types provide a way of reading ihc descriptor (context directory entry) of a single object. 
RI'AD.DIiSCRin OK specillcs the object by lilo instance id, while NRKAO.DI-lSCRlFrOR specifics it by 
CSnamc. 



30.7.2. WRITE DESCRIPTOR and NWRITE DESCRIPTOR 



requestcodc WRITE^DBSCRIFIOR or NWRlTH.DESCRlFrOR 

nameindex Hic byte offset of the name, within die segment specified by die last two long words of die 
message (NWRITH^DHSCRlPrOR only). 
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filcid File instance id of the file wliose descriptor is to be modified (WRITR_DKSCRlFrOR 

only). 

dataindex The byte offset from the start of the specified segment where the new descriptor value 

begins. 

namecuntextid The context id of tlie context in which the given name is to be interpreted 
(NWRITE.DESCRIFrOR only). 

segmentptr Pointer to a buffer which contains the object name (for NWRfl'E^DEiSCRIlTOR), and 
the new descriptor value. 

segmenden Length of the buffer. 



replycode Standard system reply code, 

dataindex Returned unchanged, 

segmentptr Returned unchanged, 

segmentlen Returned unchanged. 



'Hiese request types provide a way of modifying the descriptor (context directory entry) of a single object. 
WRr!'KJ)KSCRlFrOR specifies the object by file instance id, while NWRlTH.DFSCRinOR specifies it 
by CSname. ITic server will modify each field in the object's descriptor for wliich the value written differs 
from the existing value, if the field is client-modifiable and die new value is legal. A client normally uses one 
of tlicsc operations by first reading the descriptor, tiien modifying the field(s) of interest, and finally writing it 
back. 
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— 31 — 
Device Server 



The device server provides access to the raw kernel-supported devices via the I/O protocol. It is 
implemented directly by die Iccrnel as a pseudo-process as opposed to being a normal process like other 
system servers. Consequently, it is always configured when the V kernel is used. However, the device server 
behaves as any other 1/0 server process as far as applications are concerned. 

Tlie device server appears as a single process that supports different types of devices using tlie same I/O 
protocol. Access to a device is established by sending a create instance request to tlie pid returned by 
GetPld(DEVICR.SHRVBR, LOCAL^PID), or, if tlic standard context prefix server has been configured, by 
prefixing the device name with the context name "(dcviccr in a create instance request or Open() call. Using 
tlic standard information returned by the create instiincc request, the device can then be iicccsscd using I/O 
protocol messages, either directly or by means of tlie standard 1/0 library routines described in chapter . 
'ITiere are also some device-specific operations defined for some devices. The currently supported devices are 
described below. 



31.1. Ethernet 

'ITic Kthcrnet interface is accessed by specifying a device name of tlie form enetts. where t is replaced by die 
Htliernet type, eidicr J for 3 Mbit experimental l-vthernct, or 10 for standard Rtlieniet, and s is a suffix, which 
is null for the firet l-thernet interface, a for die second, b for the tliird. and so forth. Currently only one 
Rtliernet instance may exist at a time and only one Ethernet interface is supported, and the name eihemel is 
defined as an alias for either enetS or enel/0, whichever is present 

'Hie stzmdard header file <Vethcrneth> defines l-'themet-specinc information, including tlic Rtliernet 
packet fonnat and various constants such iis RNRl'^MAX.DA'l'A, die maximum si/.e of the data poition of 
an I Rtliernet packet. 

In a create instance request, the filcmode must be f'^CRRATR. The type of an I'-thernet instance is always a 
readable, writeable, variable block stream. 

Read and write instance requests are standard except for tlie Rtliernet block format. 'Hie H^lhcrnct is only 
sensibly accessed as a block (or packet) device, as opposed to a byte stream. The l'!Lhernet block format is 
exactly Uiat expected by die interface, namely, on the 3 Mbit litliernet, one byte for destination, one byte for 
source, two bytes for Rthemet packet type, followed by some number of daUi bytes, and on die 10 MBit 
Rthernet, six bytes for desdnation, six bytes for source, two bytes for packet type, followed by data bytes. The 
number of bytes specified in a write and returned by a read includes die desdnation, source and type bytes as 
well as tlic data bytes. 

An HUiernet-spa'ific QURRY^KIKR request is supported tliat returns tlie host number, the number of 
collisions, receiver overflows, CRC errors, receiver synchronization errors, transmission timcoULs detected, 
and Uic number of valid packets received. 'I'he host number should be used iis die source address for every 
packet transmitted. 1'he format for the request and reply messages is given by die Query HnetRequest struct 
defined in <Vedicrnct.h>. 
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31.2. MouseiThe Graphics Pointing Device 

The mouse is a graphics pointing device. It provides a means of indicating a coordinate position plus 
signalling different states via its tlifce buttons. The device server provides access to the mouse througii the 
I/O protocol, tlius viewing it as a file. 

'ITic mouse file appears as a 10-byte file divided into 3 major fields. The first two bytes specify die mouse 
button positions, the three buttons being tlic low-order three bits of the second byte. A bit with value 0 
indicates the button is up, otherwise down. The next 4 bytes specify its current X coordinate. The last 4 bytes 
specify its current Y coordinate. The kernel updates this file according to the input from the device. These 
fields are specified in <Vmouse.h> as buitom, xawrdinate and ycoordinate with MBUIT'ONl, MIBUTrON2 
and MBUTrON3 specifying die button bit field assignments in the buttons field. 

A create invStiince request for a mouse specifies the name mouse in the filename field. Only one mouse and 
one instance of that mouse arc currently supported. The filcmode field of die create instance request must be 
FCREATE 1'he mouse file instance created is initialized to have X and Y coordinates of 0. It has type 
attributes RRADAULR WRri'EABLa and FIXKDJ.HNGTH. 

Read and write requests must specify bl(Kk 0 and a byte count of 10 bytes. A read instance request returns 
10 bytes specifying the current state of the mouse "'file."' A read instance request is queued until a change to 
the mouse file (Kcurs, providing no change has occurred since die last read request. Thus, fbr instance, a 
mouse reader process that repeatedly reads from die mouse and updates a cursor is suspended when the 
mouse is not being moved and no button positions are changing. Conversely, die read returns every time a 
change does occur. 

A write instance operation cnanges die kernel-maintained record of die mouse button positions and die X 
and Y coordinates to diat specified by die 10 bytes in die buffer. Setting die mouse buttons in the kernel has 
no significant effcn:t because diis record is updated to agree with the actual button positions on die next input 
(or "squeak") received from the mouse. 

There is no need to provide a query functit)n that simply returns die current mouse position because that 
should always be stored outside die kernel. That is, the application decides where the mouse is; die kernel 
simply updates die position i-ehitive to die absolute position specified. 

The kernel does not provide any scaling of mouse movements. That is lell to the application. 

31.3. Serial Line 

ITic kernel device server provides iiccess to raw serial lines dirough die serial device. Two serial lines are 
supported, but only one instance for each may exist at a dmc. 

In a create instance request, die name serialO or serial! specifies a serial line. 'ITic Jilernode must be 
FCRRATH. The instance id returned is used for output; die instance id ■+ I is used for input. Parameters for 
die Input instance can be obtained using Query Instiincc. 

luich serial line is a pair of streams, one readable and one writeable. Characters read from each serial line 
are buflcred in the kernel until a pnicess reads from the device, but the bulTer is radier small, so a user who is 
interested in input from a serial line should keep a process "listening" to it at all limes. The serial line device 
does not provide any echoing of input characters, nor does it convert input editing or conversion of newline 
characters to a carriage retuni/linc feed sequence on output, 

The serial device drivers support QueryFile and ModifyFile operations to allow changing such parameters 
as die data rate, bits per character, and die suite i)l"Lhc modem control outputs DTR and RTS. The necessary 
message structures and constiints for these operations are defined in the standard lieader file <Vscrial.h>. (At 
this writing, die Query and Modify operations are not implemented in die Sun- 1 serial device driver.) 
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31 .4. Console 

The kernel console device is intended to provide a measure of hardware independence to programs doing 
interactive character stream input and output. The console device provides access to the console keyboard 
and display of the workstation the kernel is rimning on, independent of the type of workstiition. On 
workstations whose keyboards arc connected to serial line 0, reading from the console device reads (Vom serial 
line 0; on others, it reads from the port to which die keyboard is connected. Likewise, on workstations with 
frame buffers, writing to the console device draws ciiaractcrs on the trame buffer; for diose without, writing to 
the console sends output to serial line 0. In cases where the console uses serial line 0, instances for serial line 0 
and the console may not both exist at the same time. 

A create instance request must specify Filemodc FCRBATE, and name console. The console device is a pair 
of streams, one readable and one writcablc. As with the serial line device, die instance id returned by a 
Crcatelnstance is writeable, and that instance id + 1 is readable. The parameters of the second Instance can 
be obtained using Queiy Instance. Both instances are marked INTERACl'lVH, but SbT.PROMPT and 
SKl'.BREAK.PROCESS are not supported. 

Console device input is buffered in the same way as serial line input (sec above). The console device does 
not provide any echoing or output conversion, but it does make an effort to sound the workstiition's beeper 
when an ASCII BHL. character is output. 

The console device is automatically opened by tlic kernel upon creation of the first team, and is ordinarily 
never closed. 



31 .5. Null Devices 

Two null devices are available, and are normally configured into all versions of tlic V kernel. 'Hie nuUin 
device is a readable stream diat returns an cnd-of-filc indication on every read attempt. The nulloui device is 
an endless sink for output. 
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— 32 — 
Exception Server 



The exception server handles processes that have incurred a processor exception during their execution. It 
is included in programs that run directly under the V kernel by including a call to 
InitExceptionServerO at the beginning of the program. 'Hiis call returns the pid of the exception 
server if successful, else 0. If an exception server already exists, In1tExc8pt1onServer() will not start 
another. The pid of the exception server is also returned by 

GetP1d(EXCEPTI0N_SERVER, LOCAL.PID) 
Tlie standard V executives automatically start up an exception server. 

When a process incurs an exception, it causes a trap which is fielded by the kernel. The kernel effectively 
causes the prwcss to send a message to tlie exception server with the contents of tlic message describing the 
exception incurred. If tliere is no exception server, die kernel disables die faulting process by causing it to 
send to itself, which permanently blocks tlie process. 

The exception server checks to see if another exception handler has registered for this process or an 
ancestor. If so, it forwards tlic message to the handler. For ordinary programs, arrangements are made for 
such messages to be passed on to the V debugger (described in the V-Systcm Commands Manuaf). The Format 
of the exception request and registration messages are defined in <Vexccptions.h>. The only request types 
supported arc KXCHPnON_RKQUFSr and RHG1STHR_HANDLHR. The RHGLS'I1'K_I lANDLHR 
request code is used both for registering and dercgistering handlers. RXCHPI'ION^RHQUHS T messages 
should only be generated by the kernel. 

If no paxress was registered, the exception server prints a message on tlie screen indiciiting the type of 
exception, Uie pid of the faulting process, and the instniction, program counter and status register at the time 
die exception (xjcurred. The exception server then destroys faulting proccsji, tluis preventing it from 
doing further harm. Note: die program counter may have been incremented beyond the actual instruction 
incurring the exception so it should not be considered exact, although the error mcssijge routine attempts to 
find tlie correct PC by searching for tlie opcode of tlie instruction tliat was reported in tlie exception message. 

The exception server and its st:mdard message printing routine are included in a special V exceptions 
library. The loader may be instructed to search this library using Uic -IVexcept option on its command 
line, 'I'he error printing routine is available to other exception handlers as 

short *StandardExcept1onHand1er( req, pid, fout) 
ExcaptlonRequest *r9q; 
Processid p1d; 
File *foyt; 

where req points to Uk exception request message, p1d is the process id of die process that incurred the 
exception, and fout is rJie file on which the message is to be printed. 'Hie routine returns Uie PC value at die 
Ume of die exception, corrected as described above. 
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— 33 — 
Pipe Server 



The pipe server is an I/O server that implements a synchronized stream file called a pipe. A pipe is a 
unidirectional flow-controlled communication channel between two processes using tlie standard f/O 
protocol. V pipes are similar to Unix pipes. 

A pipe file instance is type STREAM, VARIABLE.BLOCK, and RKADABLE (for Uic read end) or 
WRITEA BLE (for tlie write end). 

In response to a CRHATH_INSTANCE request, the pipe server creates an instance of a pipe, which is 
actually two file instances representing the read and write ends of the pipe. The file Id returned in tlic reply to 
the CREATH.INSTANCH, request is the lile id of die write end. The file id of the file insuince for the read 
end is one greater tlian the lllc id for tlie write end. The file instances are owned initially by tlic processes 
specified in the readowncr and writeowner fields of tlie CreatePipcRcquest. When a pipe is created, it is 
allocated a fixed number of buffers between 2 and 10 as specified by the bujfers field of tlic 
CreatcPipeRequest. Include <Vplpe.h> in a program to define CreatePipcRcquest 

Pipe synchronization provides that a request to read a block tliat has not yet been written is queued until 
that block is written. Also, a request to write a block when die current buffer limit for die pipe is exceeded is 
queued until buffer space is available.'"* A request to read from an empty pipe whose write file instimce has 
been released is replied to with an END_OI*'_f'ILH reply code. When die read end file instance is released, 
unread datii is discarded and the data of subsequent writes to die write insumce are discarded with die write 
returning successfully. A pipe no longer exists when both die read and write instances are released. The pipe 
server periodically checks diat die owners of both file instances of die pipe exist. When die server determines 
that die owner of an instance no longer exists, it efTectively releases that instance. 

The pipe server is located by 

sepver.pid - GetPid( PIPE_SERVER, ANY^PID) 
where die pipe server may be IcK'al to the worksuuion or located on a server node. 

ITic pipe server can be compiled as an independent V program or included in another program. To include 
the pipe server directly in a V program, call die function In1tP1peSePvep( ) at die start of die program 
and cause die linker to search die pipe server library when loading die program (i.e., add -IVpipe on die C 
compilation command line). 'Hie suindard V command pipeserver may be run in die background to provide a 
local pipe seryer on any workstation. The V executive automatically stiirts up a local pipe server if diere is not 
one available when a pipe is needed. 



14 

Actually only one reader and one writer arc queued: the rest arc Fcpiicd to with a Rlil'llY reply code. 
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— 34 — 
Internet Server 



The internet server is an I/O server that provides network communications using any of several protocols. 
It is essenlially a protocol converter which allows applications which communicate by means of the V I/O 
protocol to communicate with hosts which can only (or prefer to) be rcacJicd by some other protocol. As 
such, the server has been structured in a manner which allows easy addition and deletion of protocols as 
needed. The server consists of a general framework, which *is independent of the particular protocols being 
supported, and one or more protocol-specific modules. Bach module implements a particular protocol and 
must interface that protocol to the requirements and facilities provided by the server's general framework. 
Currently die DARPA Internet protocols IP and TCP, and the Xerox PUP datagram protocol are supported. 



34.1 . Running the Internet Server 

The internet server can be compiled as an indicpendent V program, or linked into another program. 

The stiindard V command "intcrnctscrvcr" may be rim in Uie background to provide a local internet server 
on any workstation. 'l*hc intcrnetserver program by default will only register the server for die logical id 
INTERN hrr.SHRVER on a local basis. Specifying the -g opdon to the intcrncLscrver program will cause it to 
register itself globally so that it can create connections for arbitrary hosts in the V system. This facility allows 
local liosLs to avoid spending some LOOK of memory for diis server. '^^ Two additional switches arc available 
wiUi tlie internet server, -d turns on debugging print-ouls: and -q starts up a "query" process which can be 
used to query the internal state of the sei-ver from the user's keyboard. Normal usere should not need to 
concern Uiemselves with diese options; diey are intended mainly for people who are adding additional 
protocols to the server. 

To include the internet server in another V program, have it create a process which executes ihe function 

In1tInt8rnetServer(qFlag, localFlag, debugFlag) 

int qFlag; /• Set up query process for runtime 

diagnostics if qFlag is true. */ 
int localFlag; /* True if internetserver should be local. */ 

int debugFlag; /• True if debug output should be printed. ♦/ 

and cause the linker to search the V internet library when loading the program (i.e. add -IVlnternet on tlie C 
compilation command line). It is generally preferable to rim tlic internet server on its own team by invoking 
the intcrnetserver program described above, rather Uian linking it into another program. 



34.2. Accessing the Internet Server 

Once the internet server has been started it can be accessed using the I/O protocol plus the protocol-specific 
requests and parameters spcciflcd in <Vneth>. 

A CRHATE^INSTANCE request to the internet server must specify the mode FCRRATl:^. It results in die 
creation of two instances, one of type READABLE, VARIABLEJ^LOCK, and STREAM, the other of type 
WRlTliABLH, VARIABliLUI'OCK, and STREAM. 'Ilie parameters of Uie writeable inst*mce are returned 



ITiis can degrade pcrfomuincc however. For bursty appiicalions such as icinct connections it usually not a problem. 
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in the CrcaicfnstanccRcply. 'Hic readable instance has an instance id equal to the id of tlic writcablc instance 
plus I; its parameters can be obtained using QUBRY. IN STANCE. 

An internet server connection is owned by the process which requested its creation. If that process should 
die then the connection is aborted. Ownership of a connection can be passed on to another process by means 
of the SP:r.lNSTANCE_OWNER request. 



34.3. DARPA Internet Protocol (IP) 

Possession of an IP network instance provides a process access to the network for sending and receiving IP 
packets of a specific IP protocol type. Differing IP instances are delineated by the protocol field in tlie IP 
packets. Any protocol id value may be specified when creating the instance except for tliose values already 
taken. For example, the value for TCP, is already taken by the TCP implementation inside the internet server 
itself. Creating an instance with protocol 0 yields a "promiscuous" instance that receives all protocol types 
which have not been specified by any other active IP instances. 

IP network instances expect WRITH.INSTANCE to supply completely packaged IP packets. 
READ.lNSTANCI'l similarly will return complete IP packets. This approach allows IP instances to remain 
connectionless in concept and thus avoids the overhead of establishing a network connection instance for each 
different set of IP packet parameters. (Remember Uiat READ and WRITE under die I/O protocol don't 
allow for specification of parameters.) 

To open an IP network instance, use CREA TE.INSTANCE and specify tlie protocol by overlaying the 
IpParms structure definition in Vnet.h onto the unspecified field of the CreatelnstanceRequest structure. 
QUERYJ'ILE will return the value of the protocol field for an IP instance. MODIFY .FILE has no meaning 
for these instances. A standard library n)utinc, Opcnip, is provided to allow creating an IP instance and 
allocating a File structure for it. for use with other I/O library routines. 

34.4. DARPA Transmission Control Protocol (TCP) 

TCP file instances created by the internet server implement DARPA TCP byte stream connections. There 
are tlirec minor dilTcrcnccs from tlie specification in ihc DARPA Internet Mandbook. Firet the "push fiag" 
is always set ~ dativ written is transmitted over die network as s(K)n as pt)ssible. (Buffering of data is 
performed by the I/O library routines and would thus bo redundant.) Second, the urgent data fiag is not set 
as part of a write operation. Instead, a MODIF'Y.H'lI.E request is used to set the urgent data llag inunediately 
before a write operation containing urgent data. Hie urgent data fiag is reset immediately after the write 
operation and thus must be set using a MOI3II*T_FILli request before each urgent daui write operation. 
'Iliird, Uicrc is not concept of connection timeout provided. Connections arc aborted if their owner process 
goes away. 

Two variants of CREATE.INSTANCE arc permitted on instances- of type TCP, corresponding to die 
Active and Passive opens of the Internet Handbook, Note that the foreign host must be specified completely 
when issuing a CREATE.INSTANCE request with Uie active bit set A stimdard library routine. Open I'cp, is 
provided to allow creating a TCP insUuice and allocating a ImIc structure for it, for use with other I/O library 
routines. 

Two types of release mode are supported for REL1-'ASE_1NSTANCE requests corresponding to Uie Close 
and Abort primiUves of Uie DARPA specification, respectively REL.STANDARD (equal to 0, Uie normal 
release mode defined by die V 1/0 protocol) and REL.AIiORT. Releasing die writcablc instance closes the 
client's end of Uic connection. Data can still be read from die readable insttmcc until die other end closes. It 
is necessary to release both die readable and writcablc instances to deallocate a connection. 

Since TCP supports the concept of a byte stream, die RFiAD.lNSTANCE and WRITI'.INSTANCE 
operations do not segment Uie data flow in any way. 'Ilie presence of unread urgent datii in die receive buffer 
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of a TCP instance is signaled by the UrgcntData reply code to RFAD_1NSTANCE and QUERY_FILE 
requests until the urgent data has been read by the clicnL Any READ.INSTANCE requests outstanding 
when a TCP connection closes for whatever reason are replied to with a replycode indicating the reason. An 
attempt to read from a closed connection is signaled by an END_0F.F1LE reply code. 

The QUERY_FTLE operation may be used on TCP instances to find out the state of die TCP conncction. 
MODd^.FILE may be used to change various parameters of the connection. The structure TcpPannsl in 
Vneth defines the parameters which can be set both at CREATEJNSTANCE time and by means of a 
MODIFY.FILE request. The meaning of the fields are defined in the Internet handbook- TcpParmsl 
defines both parameters which may be set and state variables which may not be set but whose values are 
returned if QUERY.FILE is executed with TcpParms2 specified. The parameter in TcpParms2 which may 
be set is sndUrgFlag. This parameter is used to signal urgent data. Tlic rcvUrgFlag field returns whether or 
not urgent data has been sent from the remote host and not yet received. The bytesAvaii field indicates how 
many bytes of data are waiting to be received by the user. The state field indicates what state die connection 
is in with respect to being open, listening, established, closed-waiting-for-remote-ciose, etc. (see the Internet 
handbook). 



34.5. Xerox PUP Protocol 

Possession of a PUP network instance provides a process access to die network for sending and receiving 
PUP packets on a specific lixral PUP port. Different PUP instances arc delineated by the local socket field in 
the PUP packets. (Net and host fields will be die same for all PUP packets received by the local host, of 
course.) Opening socket 0 yields a "promiscuous" instance Uiat fields all PUP packets whose local socket 
numbers have not been explicidy registered for. 

PUP network instances expect WRITE_INSTANCK to supply completely packaged PUP packets. 
READ.INSTANCB similarly will return complete PUP packets. This approach allows PUP instances to 
remain connectionless in concept and Uius avoids die overhead of establishing a network connection instance 
for each dilTcrent set of PU P packet parameters. 

Since PUP instances are connectionless, MODIFY.FII.H has no meaning for tlicse network instances. 
QUHRY.l'lLK will return Uic value of die local socket field for an PUP instance. (QUHRY.INSTANCE will 
only return whether an instiince is IP, TCP, or PUP.) 

A standard library routine, OpenPup, is provided to allow creating a Pup instance iind alUxiating a File 
structure for it, for use wiUi other I/O library routines. 



34.6. Adding New Protocols 

This section should be of interest only to persons who wish to add an additional protocol to (or remove one 
from) die internet server. It describes tlie specifications governing Uie interactions between particular 
communications protocols and die general framework of Uie internet server. 

There are two interfaces Uiat a protocol must deal widi: tlic external interface to clients of the internet 
server, and the internal interface lo die general communications facilities iirovidcd by the server's framework. 
The external interface consists of the operations, messiige formats, etc. Uiat the protocol must understand in 
order to interface with a client's V I/O connection. The internal interface consists of tlie routines, message 
buffer convcndons, etc. diat die protocol implementation must respectively use or provide in order to send 
packets to die network and receive packets from die network. 
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34.6.1. External Client Interface 

The external interface to a protocol Is dictated for the most part by the V I/O protocol specification. 
Interaction between a client and the internet server is by means of a V I/O connection iind ttic only variations 
tliat can be effected are by means of the Query File and Modify File operations. Thus clients open a 
connection by means of tlic Crcatclnstancc operation, tlicy read and write data by means of the Rcadlnstancc 
and Writelnstance operations, they determine die general stiitc of a connection by means of the 
Querylnstance operation, and they close a connection wiUi the Rcleasclnstancc operation. 

A connection is "owned" by the client process which sent its Crcatclnstancc request, but can be transferred 
by means of a SctlnstanceOwner request The semantics of ownership are that a connection must be aborted 
if its owner process dies. One of the general facilities provided by tlie internet server is monitoring of the 
existence of connections' owners. Hovvever, the protocol implementation module is responsible for providing 
an abortion routine. 

Protocol-specific interactions are handled by means of the QueryFile and ModifyFile operations. Protocol- 
specific instantiation parameters can also be specified as part of Uie Create Instance operation. The QueryFile 
operation is used by the client to determine die state of protocol-specific connection variables; the ModifyFile 
operation is used to modify these variables. Thus the manner in which tilings such as the "Urgent Data 
Notification" tiicility in TCP must be implemented is tlic following: 

1. 11ie client's Readlnsumce operation returns an exception code indicating that something out of the 
noiTnal has happened. 

2. The client does a QueryFile operation to detciTninc the protocol-specific state of die connection and 
obtains the "Urgent Data Notification" on return. 

Similarly, a dicnt wishing to signal "Urgent Data" on a TCP connection must do so with a ModifyFile 
operation. 

34.6.2. internal Protocol Interface 

ProttKol implementations must interfticc both to die external internet server client and also to the internal 
environment of die server itself. This internal interface consists of Uic following components: 

1. A network packet butTer module which all protocols must use. Hiis module provides a pool of packet 
buficrs which have a standardized header Ibrmat so that various general facilities can manipulate tliem. 

2. A priK'CSS structure specification for the protoct)l. All protocol implementations must define certain 
processes and be aware of Uic existence of certain other processes. Part of tliis specification is a 
specification of die message interactions between tlicse processes. 

3. A set of protocoi-indcpcndcnc routines supplied by die server which all protocol implementations must 
use for such tilings as writing packets out to the network, obtaining and returning packet buffers, etc. 

4. A set of protocol-specific routines supplied by the protocol implemcntaUon which are used by the 
general server facilities to return incoming network packets to a connection, signal dmeout conditioius, 
etc. 

These components will be described in more detail in die following subsections. 



rhc reason why (he V I/O protocol spccincation has been siruclured in this manner is Tor reasons ofcfriciency. llic vast niajoriiy of 
data read and write opcrniioiis done on a connection arc doiiu with "normal" .sciiint^s for the connection panimcteni. Ry removing 
parameter speciHcation Irom the read and write q)erations these operations can be executed more quickly. 
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34.6.2.1. A Brief Overview Of The Internet Server's Structure 

The internet server consists of the following processes: 

1. A conncction-establishnlent process. This process registers itself as the internet server logical id and 
waits for connection creation requests from new clients. For each new connection creation request it 
invokes a creation routine for the protocol specified in the request. This routine is responsible for 
setting up a connection and its associated data structures and handling process(es). 

2. Connection handling processes. Each protocol connection is handled by one or more separate 
processes. It is up to the protocol implementation to decide how to structure the connection handling 
processes for a connection. However, one of these must be designated the "primary" connection 
process. 'I'his process will be responsible for handling all communications with the rest of the internet 
server, 

3. A network reader process. The V kernel allows only one network device instance to exist at any time. 
The network reader prcx:ess reads packets from the network device and calls a prottxrol-specific routine 
for each protocol being supported. The protocol-specific routines invoked arc responsible for 
determining which connection of their protocol type a packet sliould be given to. The network reader 
process mns at tlie highest priority allowed so that it can read and multiplex incoming network packets 
before tlicy are overwritten by subsequent packets in the kernel device. 

4. Two timer processes. The first timer is a timeout timer which wakes up periodically and invokes a 
timeout checking routine for each connection. If die timeout check for a connection returns a time 
which is less than Uie current time tlien a message is sent to that connection's primary connection 
handling process. The timer determines how long to sleep before waking up again by keeping track of 
the minimum timeout time beyond the current time. The second timer checks whether any connection 
owners have died. A message is sent to the primary connection handling process of each connection 
whose owner has died signalling that the connection should be aborted, liiis second timer wakes up 
once every 5 seconds. 

34.6.2.2. The Packet Buffer Module 

The packet buffer module provides a set of routines which manage a pool of packet bulTcre which arc used 
as the medium of data transmission inside the internet server. These packet buffcj-s are handed between 
various parts of the internet server by means of pointers (to avoid copy operations) and their header format 
must be undcrsKxKi by all pam of the internet server. 

The header format for packet buiTers is die following: 
typedef struct pbuf 
{ 

struct pbuf ♦next; /• General purpose link field.*/ 

1nt length; /• Length of the data in the buffer. */ 

char •dataptr; /* Location of the start of the 

data. •/ 

unsigned unspecif ied[2] ; /• Scratchpad fields. */ 
char dataCMAXPBUFSIZE]; /• The actual packet buffer. •/ 
} ♦PktBuf; 

The next field allows packet buffers to be placed in various queueing dato stRictures. 'Hie datnptr field points 
to the stiirt of tlie data, in Uie data array. Packets are typically constructed stinting from die back of Uie datii 
array, with various headers progressively added on to Uie front. The uiLspccificd fields are intended for 
storing various packet-specific items of infonnation. They arc used as scratchpad working areas. 
MAXPlJUFSr/K must be large enough to accommodate all packets encountered by Uie internet server. It is 
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set to the maximum allowed packet size of the physical nctwork.^^ 

The routines provided by packet buffer module are the following: 
PktBuf AllocBufO; 

DeallocBuf (pkt) ; 
PktBuf pkt; 

Buffers arc handed out one at a dme by means of calls to AllocBufl(). Buffers arc returned to the free pool by 
calling DcullocDufO. 'lliesc routines manipulate the buffer pool in an atomic manner; so diat they can be 
used from multiple processes without conflict 

34.6.2.3. Process Interactions 

The implementation of a protocol connection must deal with the network reader and the two timer 
pnxrcsses in a prescribed manner. In order for these processes to know whom to send messiiges to each 
connection must have a "primary" process associated with it The process ids of tlicse primary processes arc 
stored in a global data structure maintained by the internet server which contains one entry per connection. 
1lic details of tliis data structure will be described in a later subsection. 

Network Reader Interactions 

The network render process must am at high priority and cannot afford to do much prwessing because it 
must always be ready to accept incoming network packets before tJiey arc overwritten in the kernel device by 
subsequent packets. 'ITiis has lead to an interface format between the network reader and tlic various 
connection handling processes where communication is by means of atomically updated queues of packet 
buffers. Hie network reader process enqueues packets for a connection by calling the KnQucucSafc() routine, 
which places a packet in a specified connection queue. 'ITiis routine is non-blocking (i.e. no message traffic 
involved) so that the reader process can immediately continue on to pnx:css any additional packets that may 
have arrived from the network. The connection handling processes tlicn remove packet bufTcre from their 
queues by calling die l)cQucucSafc() routine. 'I1ic detinitions for these two routines are as follows: 

EnQueueSaf a(pkt , q) 
PktBuf pkt; . 
RingQueue *q; 

DeQueueSaf e(q) 
RingQueue *q; 

RingQueucs are atomically updated queues which are defmed in the general internet server module. They 
must be initialized with calls to the InitSafcQucuv() routine: 

InltSaf eQueue(q, rIngBufs) 

RingQueue *q; /♦ Queue header. */ 

RIngBufRec PingBufsC]; /* An array of MAX<-RING*-BUFS queue 



records. •/ 



RingQueucs consist of tlic following two data types: 



17 

Nolo ihai there is only one packci buiTcr size for (he entire internet server. A single buiTcr size was chosen primarily for reasons of 
simplicity. Ilxicnding the paclccl buiTcr module tu handle multiple hulTcr sizes would mH be difTiculL 



18 

I.e. it niu.st be able to keep up with the (possibly many) hosts that arc sending it packets. 
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typedef struct 
{ 

RingBuf head; 
RingBuf tail ; 
} RingQueue; 

typedef struct RIngBufType 
{ 

PktBuf pkt; 

struct RingBufType *next; 
} RIngBufRec, ♦RingBuf; 

The RingQueue structure defines a header record for the queue. RingBufRecs arc the actual queue clcmenLs, 
and are placed in a circular list by the JnUSafcQucucQ routine. The pkt field of a RinglJuflicc is used to 
point to the packet buffer which is enqueued by it. 

Note that at most MAX - RING - BUFS packet buffers can be enqueued in a RingQueue. KnQucucSafcQ 
returns 0 if it can't enqueue a packet buffer. 

There is one caveat to the above de^5cription of how tlie network reader interacts with individual 
connections. The primary connection handling process for a connection may be bkxrkcd waiting on client 
requests'^^ so tliat the packet buffer queue cannot be prcx'cssed until a request message is received. To take 
care of Uiis case each primary connection process must also set a variable indicating whether it is bl(x:king 
awaidng client requests or not. The network reader checks this variable when cnqucucing a packet for a 
connecuon and sends die connection a "wakcup" message if it is bk)cked. The process receiving die message 
must reply immediately to this message in order to minimize die time diat die network reader is blocked. 

Another point to be made here is Uiat die actions for die network reader described above (i.e. invocation of 
KnQucucSafcO and checking to see if a "wnkcup" message must be sent) are actually part of the protocol- 
specific "network reader" routine diat each protocol must supply as part of its implementation, niis will be 
described in more detiiil later. 

Timer Intcnictions 

The two timer processes communicate with connections by means of "timeout" messiigcs. Whenever a 
timeout condition is detected by a timer process it sends a message to die relevant connection process 
indicating diat a timeout condition has (x;currcd. The message format employed is the following: 

Struct timeoutMsg 
{ 

SystemCode requestcode; /* Standard message request code 

field. •/ 

short unused: 

unsigned timeoutCondltlon; /* Which timeout has occurred. */ 
unsigned unusedl[6]; 

}: 

The requestcode field is the same as Uiat used for all other message requests. However, instead of a 
"sumdard" V I/O protocol request code an internet server-specific request code signalling dmeout is used. 
The timuoutConditlon field specifies which timeout condition has occurred. 
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The rciLson why a circular queue of ihis form Is needed stems from (he problem of maintaining these queues in an atomic manner. 

20, 

Ilic protocol iniplunientnifoiis to date have consisted of a single process per connection which alternately waiLs on client requests 
and processes it paclccL bulTcr queue. 
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34.6.2.4. ProtoGoMndependent interface Routines and Data Structures 
Gloi>ai Data Structures 

There is one global data stmcturb that must be maintained by all active connections in the internet server. 
This is the NctlnstTaliic, which contains an entry for each connection specifying various V 1/0 prot(x;ol- 
spccific parameter values, the process id of the primary connection handling process, and a pointer to a 
control block associated with that connection. 'ITic V I/O protocol parameter infomiution Is used by the 
Query InstanccO routine for answering Query instance requests about connections.^*^ 'Hie process id is used by 
the network reader and timer processes to find the primary process for a given connection. 'The control block 
pointer is used to access connection-specific information. It is intended for use by the protocol-specific 
network reader and timeout checking routines. 

llie primary manner in which connections manipulate the NctlnstTable is tlirough the following two 
routines: 

1nt A1 1ocNetInst(prot. ownerPid, p1d, rblocksize, wblocksize, tcBId) 
int prot; /• Connection protocol type 

(TCP, PUP, etc.) «/ 
Processid ownerPid; /* Process id of owner of the 

connection. •/ 

Processid p1d; /* Process id of primary connection 

handling process. */ 

Int rblocksize, wblocksize; /• Block sizes for resp. read and write 

V I/O connection instances. */ 

unsigned tcbid; /* Pointer to the control block for 

this connection. ♦/ 

Deal locNet Inst ( index) 

int index; /* Index of NetlnstTable entry to 

deallocate. •/ 

AllocNctliistO returns an index into die table where die newly all(x:ated entry has been placed. Individual 
fields can then be set by indexing through this value into tlie table. (F.i.g. SctlnstanceOwner requests would be 
dealt with in diis manner.) 

Fach protocol implemcntadon is expected to employ these routines to manage die NctlnstTable in a correct 
manner. I.e. allocation and deallocation of NctlnstTuiiic entries is noi done automatically by the server's 
general facilities. 

Useful But Not l*!sscntial Routines 

ITic internet server provides several generally useful but not essential routines which may be employed by 
protix:ol implementations if they so chose. 'Iliesc include the following: 



llicsc requests arc actually directed at the connection handling processes thenisclvcs, implying thai each connection could employ 
its own Query Instance routine, i iowcvcr no benclK would be gained by such duplication. 
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SystemCode Querylnstanc8( rqMsg) 
QuerylnstanceRequest *pqMsg; 

Boolean Inval idFileid(rqMsg) 
loRequest *pqMsg; 

ReplyTGRead(r8plycod8, pid, packet, bufferPtr, length) 

SystemCode replycode; /* Reply code to send to a reader. */ 

Processld pid; /* Process id of the reader. ♦/ 

PktBuf packet; /* Packet buffer containing data to 

return to the reader. NULL if 
there is no data to return. */ 
char *bufferPtr; /* Address of reader's buffer. */ 

int length; /« Length of data to return. */ 

QueryProcessO- 

QucrylnstanccO returns the slate of a specified network connection. It is V I/O protocol-specific and hence 
independent of tlie particular network protocol being supported by die other end of the connection. It 
obtains its information from die NctlnstTablc entry for die connection. Connections arc specified in the 
request message in die same manner as with all other V I/O connections, namely by a filcld. 

IimilidKileidO ciiecks whether tlic fileid field in a client's request message is reasonable: i.e. whether it maps 
to an existing connection entry in NctlnstTablc which is in use. All incoming client requests should be 
checked with diis routine to avoid corruption of other connections' control blocks. 

RcplyToRcndO is a generic routine for replying to a client's read request. It performs the MoveTo 
operation needed to move data from a packet bufibr to the client's read buflcr and packages an appropriate 
reply message. 

Query !*roccss() is a routine which mns in its own process and is used for debugging. It provides a means 
for examining and changing the state of the internet server while it is in operation. 

34.6.2.5. Protocol-Specific Interface Routines and Data Structures 

There are two types of protocol-specific routines that a protocol implementation must provide: network- 
level routines and connection-level routines. Network-level routines arc used by die network reader process 
to multiplex incoming network packets to die correct connection. Connection-level routines ;irc used to 
initialize a protocol, create a new coiuiection and interface with die connection timeout checking prt)ccss. 

Protocol implementations arc usually done for prolocol families rather Uian individual protocols. For 
example, the current internet server implements both die IP and die TCP Internet protwols. However, raUier 
Uian implementing these two protocols as separate modules, diey are implemented together, so that the TCP 
module can make use of facilities already defined by die IP module. This results in a situation where only die 
IP module interfaces with die network layer and die TCP module interfaces internally to die IP module. Thus 
die IP/TCP protixjol family implementation has three interfaces to die rest of die internet server rather than 
four: it has a single network-level interface and a connection-level interface for both 11* and TCI* respectively. 

Protocol-specific interface routines arc accessed by die general server facilities dirough function tiibles 
indexed by protocol type. There are two such function tables, one for die network-level routines and one for 
die connection-level routines. The format of these tables is described below. 

Nctwork-lcvcl 

llic network-level function tabic is called Pnct'l'ablc and is defined as follows: 
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Struct PnetBlock 
{ 

unsigned prot; /* Network protocol type. */ 

Boolean active; • /* True 1f a network connection is 

active for this protocol . */ 
1nt (*1n1tNetProt() (); /• Initialization routine for this 

protocol . */ 

int (*rcv) (); /• Receiving routine for this 

protocol . •/ 

} PnetTable[NumPnetProtocols]; 

The first two fields are actually not functions. The prot field is used to store the networii protocol type id so 
that the networlc reader process can figure out which table entry to use for a given network packet. 

The active field is used to allow the network reader process to "short circuit" discarding of broadcast and 
invalid packets for inactive protocols. Without tliis field the reader process would have to call the rcv() 
routine for these packets since it can't tell itself whether they should be discarded. The active field is 
managed Uirough the following two routines: 

ActivateNetProtocol (prot) 
int prot; 

DeactiveateNetProtocol (prot) 
int prot; 

prot specifies which table entry to access. 

Associated with the active field is another tijble, called NctLcvclProtocol, which is used to map from 
connection protcxrols to tlie network-level protocols which support them, b'or example, the IP/TCP protocol 
implementadon described previously would designate both IP's and TCP's network-level protocol as being 
■ IP. The definition of the table dati\ structure, along witli an example initialization is as follows: 

int NetUevel Protocol [NumProtocols] » 
{ 

0, /• IP •/ 

0, /* TCP ♦/ 

1, /• PUP */ 

>; 

'Hie index of each entry corresponds to Uic index of die corresponding protocol entry in Uie l*'unc Table l«ible. 
The contents of each entry is Uie index oftlie corresponding network-level protocol in Uic Pnct Table table. 
'Thus, in die example shown, die Kunc'Table defines die IP protocol at index 0, die TCP protocol at index 1, 
and die PUP protocol at index 2. 'Hie I'nct rahlc defines die IP network-level protocol at index 0 and the 
PUP network-level protocol at index l.^ 'The initNctProt field specifics an initialization routine for the 
prot(x:ol which is called at server boot time. 

'Hie rev field specifies a routine which is called whenever a network packet arrives which has a prot(x:ol type 
equal to diat specified in the prot field of die entry (^ind die active field is true). 1 his rouiinc is responsible 
Tor figuring which connection of its prol(x:ol, if any, should receive die packet Ifa connection is found dien 
die rouiinc is responsible for enqucucing die packet in diat connection's KingQueue (using die 
linQucticSafcO routine) and for checking to make sure that die connection's proccSvS(es) will actually be able 
to process die enqueued packet bufi'cr, (I.e. if die connection's proccss(es) are reccive-blockcd awaiting client 
requests dien die routine must send a message to "wake" diem up.) Packets for which no connection is found 
must be returned to die free butter pool with a call to l)c:illocBur(). 



actual inlcrnct server code usch ninniTcRi coii.s(nn(.s instead of inlcgcra lo nil these fields - making things much more rcadabta 
I lowcver, to iilu»iratc Uie principle, no manircsts were employed. 
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The interface definition for the inilNctProtO and rcv() routines is as follows: 
InltNetProtocolO 

Rec8ivePPotocolPkts( packet) 

PktBuf packet; /* PtP to" the incoming network . 

packet. •/ 

where InitNctProtocoK) and Receive ProtocolPktsO arc example names. 
Conncction-Icvcl 

The connection-level fiinction table is called FuncTabIc and is defined as follows: 
struct FuncBlock 
• { 

int (*InitProtocol ) (); 
SystemCode (*CreateConnection) (); 
int (*NextTim80ut) (); ] 
} FuncTabl9[NumProtoc9ls] ; 

The initProtocoi field specifies an initialization routine for tlic protocol which is called at server boot time. 

The CrcatcConncction field specifies a routine which is called by the connection-establishment process 
when a client requests tlie creation of a new connection instimcc. The routine must create tiic data and 
process structures for a new connection and then handle the Create Instance request from die clicnt.^"^ This is 
usually also the place where a call to the ActivatcNctProtocol() routine is made to signal that tlie protocol is 
active. 

Hie NcxtTimcout field specifics a routine which is called by die timeout checking timer process. This 
routine returns tlic time of the next timeout for its connection. If that time is already past tlicn tlie timer 
process will send a timeout message to the connection's primary pr(x:css. The connection's data structures are 
accessed through the tcbid field of tlie connection's NcthistTablc entry. 

Hic interface definition for the InitProtocolO, CrcatcConncctiow(), and NcxtTimcoutO routines is as 
Ibllows: 

InitProtO 

CreateProtCQnn8Ction( peqMsg , cl ientPid) 
CreatelnstanceRequest reqMsg; 

/* Createlnstance request message sent 
by a the client. ♦/ 
Processid clientPid; /* Process id of the client. */ 



NextProtTimeout(tcbld) 

unsigned tcbId; /* Ptr to the control block for the 

connection. ♦/ 

where inilPro((), CrcateProlConiiectioii<), and NcxtProt TiiiicoulO arc example names. 



Hie method recommended for doing ihis is lo have tiic roiiiinc create the connection handling pr(Kcss(cs) and ihcn Torward Uie 
Createlnstance request to the connection's primary process. This allows the conneciion handling praces.s(cs) to nismipulatc their own 
diita .structures (which arc typically kept on the procc!is(cs)' siack(s)). 
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— 35 — 
V Storage Server 



The V storage server is a file system tliat implements the V I/O protocol. It is intended to nm on a "server" 
machine with mass disic storage, thus providing file access for users on the nctworic. It provides an alternative 
to the Unix Server for file storage. It implements a hierarchical name space with a syntax very similar to that 
of the UNIX file system (i.e. pathname components are separated by a "/"). Additii)nally, there is no 
distinction between files and directories in tlie V storage server (i.e. any file can "act" like a directory in that it 
can have descendents in the tree stnicture). 

One word of caution is that tlie V storage server is still at an "experimental" stage, thus providing limited 
access facilities and no protection. Hence, users requiring robust file access and proteciton should use the file 
storage provided by the Unix Server. The robustness of the V storage server software is expected to greatly 
improve in die near future. 

35.1 , Running the V storage server 

One can start up the V storage server from within a V executive by typing 
storagesarvor 

or 

storagesepver devicename 

If no device name is specified, the storage server attempts to open two devices, [dcvicc]diskO and 
[deviccjdislci. Non-existence of a second device docs not affect correct operation of the program. Note that 
the devices must be attached to die workstation from which die command is invoked and die kernel running 
on the workstation must include the proper disk driver (see die Kernel Section for details on which kernel 
should be booted). 

35.2. Accessing the V storage server 

When die V storage server is started it registers itself as VSTORAGR^SKRVHR. Thus, before a client can 
communicate with die V storage server it must do a GetPid( VS^ORAGl•:_SI^RVb:R, ANY.PID), This 
function returns a pid to which a client will send its CRHATl^INS TANCH request messages. 

A CREATE_INSTANCIi request caases the server to attempt to open die named file. ImIcs opened in 
FRHAD mode arc of type RKAI)ABI.I% l-'lXHn.LI':NGTH, and MUI/l'LULOCK. The modes l-CRHA TH 
and F'MODIl'Y create instiuiccs of type RKADAIU.I', WRi ri'AUl and MUKTLIJI-OCK. I-AITHNO 
mode adds die further constraint of AI*PI^ND„OMLY. All instiinccs are randonj access, but operations nuisl 
start on a block boundary. 

If die mode is FCREATE, and the file does not exist, then a new file is created along with die associated 
instance. The permission bits of die new file will be Uic same as diosc of its parent node in die directory tree 
structure. 

If a CREATH_fNSTANCR request is successful, a file instance idendfier is returned by the server that is 
used by die client for all subsequent accesses to this instance. In addition, die server returns a Jifc inskmcc 
server pid which is die process to which all subsequent I/O requests will be directed. This pid is di^Terenl 
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than that of tlic main server because one proccSvS (namely, the one registered as the VSTORAGE_SERVER) 
handles CREATE^INSTANCE requests and other processes handle I/O requests. 

Once an instance has been created, a client can perform I/O operations on the file represented by the 
instance using READ.INSTANCE and WR1TE_IN STANCE requests. These requests, if legidmate, result 
in the file instance j<?rver carrying out the desired tasks. When a client is finished accessing a file, it closes the 
file by issuing a RELEASH.INSTANCE request. 

The V storage server supports many other types of requests including ones to create, remove, and rename 
files and most other relevant requests associated with the V I/O and naming protocols. Note that many 
applications need not be concerned with message types and formats as actual message construction usually 
takes place within V commands and standard library roudncs. For example, CREATE_INS1'ANCE, 
READ.iNS'rANCE, WRITE.INSTANCE, and RELEASE_INSTANCE requests are encapsulated in the 
library routines Opcn(), Read(), WritcQ, and Close(), respectively. 



35.3. Creating a context for the V storage server 

In order to provide easy access to the V storage server and its directories, it is convenient to define a context 
for it using the define command. Once this is done, one can simply cd to the newly created context and 
subsequent relative patli names will be interpreted relative tu this context 

'Hius, for example, 

define ss [storage] 
results in a context being defined for die V storage server, and 
cd [ss] 

causes the user's current context to be changed to its root directory. 
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— 36 — 
Unix Server 



The V Unix server is a Unix program (and not a V program or command) designed to simulate a V 
kernel/storage server on a VAX^/Unix system. It provides access to some of the Unix system services via the 
V kernel interprocess communication primitives. To workstations running the V kernel, the Unix server 
appears as a standard V server, primarily providing Unix file access using the standard V I/O protocol. 

GetP1d(UNIX_SERVER , REMOTE_PID) returns the pid of a Unix server accessible to this workstation. 
With more than one, G<3tPi d( ) returns the pid of the first Unix server to respond to the request. This is the 
pid of a public Unix server. Public Unix servers also register themselves under the logical pid 
STORAGE.SRRVER. A public storage server is the definitive source for all the standard system files and 
commands whereas hosts that run non-public storage servers arc not required to be kept up-to-date. 



36.1 . Sessions 

TTic public Unix server provides access to all files on a Unix host that are publically readable (in Unix 
terminology, "readable by others"). To get access to other files, a client must create a session with tlic Unix 
server. To create a session, the client sends a CREATE_INSTANCE request to the server, with the mode field 
set to.FSHSSlON+FCRHATH. The name field of the request contains a Unix user name and password 
(separated by a NULL character). 'ITie reply message will contJiin tlie process id and instance id of the session. 
'Vhc process id allows Uic client to communicate directly with the session. The session provides several Unix 
system services, all running under die access privileges of die Unix user specified in die 
CRKA1TJNSTANCE request 

The initial owner of a session is specified by a server-specific field in die CRKATE.INSTANCH request. 
The format of Uiis request is defined in die stimdard header file <Vsession.h>. 

nic operations SI-TI'.INSTANCILOWNI'R and RRLFASK.INSTANCE arc meaningful on session 
instances. Other I/O protocol operations arc currently not supported. Releasing a session instiince terminates 
the session and invalidates its process id. 



36.2. File Access 

When a CRHATE_INSTANCH request is received by die server (or session), and diere are no special mode 
Hags set (such iis FSHSSION), it attempts to open die named file. As was menUoned earlier, the file must 
have others access privileges in order for it to be opened by die main server. Also, the main server docs not 
allow creation of new Hies, or writing to any file. A session, on the other hand, has the same access privileges 
as die Unix user Uiat created it 

If die client has the correct permissions, dien an instance is created, with die type field set according to die 
request mode. Files opened in FREAD mode arc of type READABI.E, I^^IXED LENGTH, and 
MULTLULOCK. 'Hie modes FCREATE and FMODIFY create instances of type READABLE, 
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WRITEABLE, and MULTU5L0CK. FAPPEND mode adds the further constraint of APPHND.ONLY. 
All instances are random access, but operations must start on a block boundary. The block size of these 
instances is equal to the maximum appended segment size for V kernel messages. 

If the mode is FCREATE, or it is FMODIFY and the file docs not exist, then a new file is created along 
with die associated instance. Files are created witli Unix file protection bits ("mode bits") set to allow reading 
and writing by the owner, and reading by group and others. A client may change the mode bits using a 
WRlTE.DESCRlFrOR or NWRrrH.DESCRlPrOR request 



36.3. Program Execution 

A client can execute Unix programs through a V session by sending a CREA TE. INSTANCE request with 
the FHXKCUTH Hag set in tlic mode field. The name and ai'gumcnts of the program to be executed are sent 
in the segment with the NULL character being a field separator. The last argument need not be null- 
terminated. Ilie context in which tlie program is to be executed is also specified in the request 

Given a request the session has a built-in search path that it uses to determine which Unix program to 
execute.^'* The session tries to find the firet file in a directory along the search paUi that matches the given 
name. If the name contains a V\ tlicn the search patli mechanism is not used and only Uic context specified in 
the request is searched. If the program is a shell script tlic l^ournc shell is invoked explicitly, and it 
determines which shell should execute the script based on Uie nonnal Ikrkclcy Unix conventions. As a 
side-effect the shell expands any wild-card characters (such as and T) found in the arguments, lliis 
expansion docs not (x:cur if die Unix program is not a shell script 

After all of die preliminary checking is done, tlie session forks and its child attempts to am the program. 
The parent process replies to the requestor with an OK stotus. However, there is no guarantee that the 
execution will be successful. A failure am (x*cur after the OK reply has been returned, since die program is 
not loaded until the child has been forked oft' and tlie reply is sent asynchronously. If a failure of this nature 
occurs, Uien an error messiige should appear in die program's output 

In die reply message, the session includes an instance id for the nmning program. If die file mode in die 
CRKA ri'.lNS TANCH request was I'REAl), Uien the instance id specifies an instance of type READABLE, 
VARIABLE.ULOCK, and STREAM. 'Hic client can read die program's sumdard output using this instance. 

If die mode was V'CRHAIL, PMOIDI^Y, or FAPPENO, then the instance returned in the reply message is 
of type WRI THAULK VARIABLE.BLOCK, APPI'ND.ONLY, and STREAM. Data written into Uiis 
instance is piped into Uie program's standard input An insUince with id 1 greater diun tlic one returned in the 
reply is also created, of type READABLE, VARIABLE.IJLOCK, and STREAM. Reading from diis instance 
provides access to die program's standard output 

When die program terminates (cither normally or abnormally), the session returns an END_OF_FILE 
reply to any write requests. Read requests will continue to be accepted as long as data is left in die pipe. 
Write requests will block if tJie pipe is full and tlic Unix program is not reading from it (Unix pipes can 
bulTer up to 4096 bytes of data.) 

A client may icrminate the program by releasing all instances ass(x;iated with it If only one of the instiinces 
is closed, tlien program will not terminate inunediately. 'Iliis allows a client to close tlie program's input and 
have it clean up before exiting. One should be careful not to release die readable instance before program 
termination, because Unix sends a signal to any program that writes to a pipe with only one end. The signal 
will kill the Unix process, if the process is not catching or ignoring it 



To find out ihc search pnth used' in your insiallalion, execute the Unix command printanv. This will display the environment 
variables that arc pxsscd on lo programs executed via the session. 
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36.4. File Descriptors 

The server supports the V context directories and descriptor requests. One can open a Unix directory with 
the FDIRECTORY flag set in the mode field and the server will automatically translate standard Unix 
directory entries to V Unix file descriptors. Directories are not writeable directly, but descriptors can be 
modified using a WRI'rE.DESCRiJ^rOR or N WRITE JOESCRlPrOR request. The UnixFUeDescriptor 
type is defined in the system include file, <Vdirectoi7.h>. 



36.5. Server Name Lookup 

A client can get the pid of any Unix server by sending a LOOKUP^SERVER request to another Unix 
server. The request and reply formats are as follows 



requestcodc LOOKUP.SERVER 

hostname Pointer to the character string name of the host on which the server is running, 

namclength Length of the host name. 



rcpiycodc Standard system reply code, 

scrvcrpld Process id of the server. 



The hostname field of tlie request gives die name of die host machine that tlie requested server is running 
on. The server's pid is returned in die serverpid field of die reply message. These message formats are defined 
in the standard include file <Vscssion.h>. 
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— 37 — 
Service Server 



37.1 . Overview 

The service server provides a means for managing globally visible servers and services. It provides facilities 
for registering arbitrary objects (typically entries wiiicii describe the state and contact address of a server or 
service) and also for selecting a subset of these registered objects for retrieval! 'ITic selection facilities take a 
client-specified pattern and match it against the information in each registration entry to determine whether 
that entry should be included in the retrieval scL 

Since any kind of object can be registered, the server is in fact a general "switchboard" service which can be 
used for arbitrary "rendevous" between two or more clients. However, the primary usijge of this server is 
intended to be for management of global servers and services; and die selection facilities provided for 
retrieving registered objects have been structured with this goal in mind. 



37.2. Registering an Object 

Objects arc registered with tlie service server by means of the R8g1st9rServer( ) library routine. This 
routine pacicages a registration descriptor into a message and sends it to tJie service server. Registration is on 
the basis of an object name and an object type. Object type essentially represents a subcontext within tlie 
service server and all objects of a given type must be registered using Uie same registration entry record 
structure. Object name distinguishes between the various registered objects within a given object type. All 
selection and listing of registered objects is done with respect to a given object type. 

The service server maintains Uie concept of an owner for the objects registered with it. Registered objects 
are unregistered when their owner dies. 'Hiis is achieved by having the server periodically check each 
registered object's owner's process id to see if it is still valid. The ownership of a registered ol^ject can be 
changed using the stanclxird SdtInstanceOwner() library routine. 

The format of the registration entry for a particular object type is left to Llic client. Thus an entry can store 
arbitrary sorts of information in it. However, in order to be able to perform selections of registered objects on 
die btisis of information contained within Uieir descriptors die formats of Uie relevant descriptor llelds must 
be known to the service server's pattern matching facilities. To support tliis, several well-known descriptor 
formats have been defined in tlic C include file Vservlce . h. These record .structures are actually descriptor 
format prefixes since the client can append arbitrary numbers of additional fields on die end of the descriptor 
structure which contain information not used in the selection process. 

There arc various well-known object types (and associated registration descriptor fonnats) which are 
defined in Vservlce.h. The.se are utilized by various existing facilities such as liie team servera of all hosts 
throughout Uic system. 

Objects can be unregistered by means of die Unp9g1sterServer( ) library roudne. Objects already 
registered can be reregistered with a new descriptor entry by simply invoking die Re9istdrServer( ) a 
second Ume. 'Hie service server will automatically remove the original entry. 

'I'he service server has a well-known multicast group associated widi it which it uses to send out requests for 
status update when it first starts up. This allows it to reinitialize itself after crashes and odier such events. The 
welt-known multicast address is defined in die Venvi ron . h header file. 
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37.3. Listing Registered Objects 

All registered objects' descriptors of a given type can be listed using tlic standard V directory listing 
protocol. Similarly, a single registered object's descriptor can be listed using the NRcadDcscriptor request 
defined in this protocol. The format for specifying an object is 

object-type: object-name 

If no object type is speciiied in the Croatelnstance request message then all registered objects are 
returned. 

Since the service server understands the V directory listing protocol it is possible to use the 1 i s td1 r() and 
UstdescO programs to query it from die exec level. Ilius, for example, the status of all running hosts 
within the system can be found out by typing 

I1std1p [sepv1c8]host 
to the V exec to query the well-known object type host. 



37.4. Retrieving Sets of Registered Objects 

Sets of registered objects are retrieved from die service server by means of a combination of service 
server-specific library routines and general V-l/O prot(x:oi library routines. The basic idea is to establish a 
connection instance, just as for a V-I/0 protocol connection, through which the descriptors of die selected 
objects are read as if Uicy constituted a separate file unto tlicmselvcs. The selection instance is created using 
die Creat8SelectionInstanc8( ) routine, which specifics which set of objects to retrieve. The instance 
is subsequently treated just as if it were a standard V-I/0 instance: which can be read using standard library 
routines such as Read( ) and is released using the standard library routine C1ose( ). The only difference is 
Uiat die first descriptor associated with Uic selection instance is immediately returned by die 
CraataSelectlonlnstanca operation. 

Since Uicrc arc many cases where one wants only the first object returned from a set of selected objects (e.g. 
the first host from a set of hosts eligible us remote execution sites) a means is provided by which a single 
object descriptor can be retrieved without incurring the cost of estiiblishing a selection instance. One of the 
paramcten* to CreateSelectiohlnstanca allows one to specify whether one or more than one objects is 
to be returned. If only one is specified then no connection is . csuiblishcd and 
CraataSalactlonlnstanca merely returns Uie desired descriptor record. 

Selection of objects is based on die specification of both u retrieval pattern and a pattern matching function. 
As mentioned before, all selection is done stricdy within a given object typo. The pattern matching function 
to specify is determined by die format of die descriptors for die desired object type. The include file 
Vservica.h contains a list of all available pattern matching functions and descriptions of the descriptor 
formats diey expect to use. Hits include file also contains a description of die form diat retrieval patterns 
must take as a fijnction of which pattern matching function is to be used. 



V-SYSTliM 5.0 RP-l-ERI-NCl' MANUAL 



SERVERS 



EXEC SERVER 



189 



— 38 — 
Exec Server 



The exec server is central control facility for all instances of the V system executive on a workstation. Its 
purpose is to allow sharing of code and data (such as aliases) among all executives. 1'he intention is that while 
each executive is a separate command stream, all executives on tlie same workstation should present the same 
command interface to the user. That includes customized aspects of that conunand interface, such as aliases. 
Since the exec server is part of the basic equipment of the V system, such customizations do not vanish even if 
the terminal agent is replaced, but as long as die user is logged in. 

'nic exec server is located by 

Ge tPi d( EXEC^SERVER , LOCAL+-PID 

It is present in all the standard configurations of the Vsystem. 

The exec server allows programs to have instances of the executive (usually referred to simply as "execs") 
created and destroyed. An exec is known to the server by its exec id; exec ids are small integers starting at 
O.lTiere is currently no concept of ownership of execs-any program can destroy any exec regardless of 
whetlier It created it or not 

The following requests are supported. 

CRI£ATE-KXECCreates an executive, with standard i/o and context specified In the request message, and 
returns the exec id. 

START -tB-IXKC Under some circumstiinces an exec is not started by die CRRA TH— H^XEC request, 
because the requestor needs to do some SctlnstanceOwner operations first. 
START- EXEC then allows tlie exec to start amning. Normally all tliis is transparent and 
is handled in Crcutcl'lxcc. 

DELE'i'E-EXI^Cnelcte an executive. If there is a program running under it, it is abruptly stopped due to 
die dcaUi of its parent process. 

KILL- PROGRAM 

Kill the program nmning under an executive. If there was no program running under that 
executive, nothing happens. 

QUERY- EXEC Returns information on an executive: Its status (free, loading a program, or nmning a 
program), its process id, and the process id of tlie program running under it, if any. 

CHECK - EXEC Makes a check of all executives.; If Uie standard input server or standard output server of 
an exec has died, Uic exec is destroyed. This is used mainly when changing terminal 
agents. 
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— 39 — 
Terminal Agents 



Terminal agents are a generic class of scsrvcr used in the V system. A terminal agent has tlic duty of 
mediating between the terminal hardware, the user, and the other programs in tlic system. It is responsible 
for line editing functions,e.g. the fact that tlic back space key docs not add a backspace character to the impiit 
stream but deletes a character from the imput stream. It translates tlie newlinc character '\n' into a carriage 
return/linefeed sequence on terminals that require it. It is also responsible for interacting with the exec server 
to create at least one executive, or providing means for the user to do so. It may, but need not, support 
multiple i/o streams. Terminal agents may diflcr for two reasons: because tlicy are designed to offer dilTcrent 
services to tlic uscr« or because they arc designed to run on different types of tcrminafs. 

The V system currently contains two different terminal agents, the Simple Terminal Server (sts) and the 
Virtual Graphics Terminal Server (vgts). The Simple Terminal Server is a minimal terminal agent. It 
provides a single i/o stream, using the terminal facilities provided by tlie firmware monitor of the workstation, 
and creates one executive using tliat i/o stream. The standard V line editing interface is provided, but no 
mouse or graphics facilities are available. The Virtual Graphics Terminal Server, in contrast, provides a very 
large set of facilities: multiple i/o streams in multiple windows, graphics, and mouse-controlled menus. Ikit it 
supports die same line editing fticilities. A large class of programs should be able to run under either of these 
terminal agents, or any other teiminal agent, without any knowledge of which terminal agent is present. 

The ncwtcnn command allows the user to replace tlie terminal agent on his workstation without rebooting 
the workstation. 



39,1 . Implementation of Terminal Agents 

These are the requests that should be supported by a terminal agent, at tlie minimum , It should support 
tlic V I/O protocal for INTl-RACl'lVH STRHAM files. In simple cases, it may give polite replies to 
CRI^A TH-INSTANCP: and RHLHASF,- INSTANCHl without really doing anything, as the sts does. It 
should also support the MODIl'Y — 1''1LH request in the fashion expected by IVlodifyPad: it sets the pad 
mode, with a combination of bits controlling such features as line editing, echoing of input, nnd translation of 
\n to carriagc-rcturn/Hnefecd. In particular,ModiryPij(l<fik\0) should turn olTatl such features, giving the 
client access to tlie raw, unadorned terminal. 

Tlic following conventions should be observed, in order to allow the ncwtcnn command to work: Upon 
starting up, a terminal agent should define tlie context (scrcenj with itself as the server. It should also support 
tlic GctRawlO request message, in which tlic terminal agent tells die client the sei'vcr and instiincc id's lor its 
own standard input and output. Presumably Uicsc refer to Uie raw terminal. 
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— 40 — 

Virtual Graphics Terminal Server 



The Virtual Graphics Terminal Service (VGTS) allows the display of structured graphical objects on a 
workstation running the V system. This chapter describes the internal structure of the VGTS. The SDF 
manager was originally written by "Rocky" Rhodes, incorporated into tlie Yal e program by Tom Davis, and 
converted to use the V kernel by Marvin Theimcr. The current VGTS is die work of Bill Nowicki. 



40.1 . Current VGTS Versions 

There arc currently two working versions of the VGTS. sunlOOvgts is used on workstations witli SMI 
model 100 framcbuffcra, while sunlZOvgts Is used with tlie SMI model 120 framcbuffcr. Users usually will 
not have to concern themselves with this, since taaml'vgts (the default first team) automatically loads Uic 
correct version of the VGTS. Furthermore, the program vgts is a 'bootstrap' program which loads the 
correct version of the VGTS (in a new team), and then dies. Thus, "vgts" can be given as an argument to 
newta rm (see Section 4), regardless of the framcbuffcr type. 

llxe difference in VGTS versions is Important, however, when loading special first teams that have a VGTS 
already linked in. team 1+ sunlOOvgts] will run only with a SMI model 100 framcbuffcr, and 
team I + sun I20vgts] only with a model 120 framcbuffcr. 

40.2. VGTS Philosophy 

The central concept of die VGTS is that application programs should only have to deal with creating and 
maintaining abstract graphical objects. The details of viewing these objects arc token care of by the VGTS. 
This is in contrast to traditional graphics systems in which users perform the operations directly on tiic screen, 
or on an area of the screen referred to as a viewport or window. The types of objects managed by the VG I S 
arc discussed in mure detail in the VGTS chapter of the librai7 manual. 



40.3. VGTs, Views, and Instances 

Once tlie VGTS client has defined some graphical objects, it also needs to provide information on which 
objects can be viewed. Hvcry K(77is an item (usually a structured symbol) tliat is associated with one or more 
views, that actually appear on tlic screen. Hach VGT can exist in zero or more views, but each view h.'is exactly 
one VGT associated with It The "SDF Niunbere" can be thought of as separate object defmition spaces, while 
the VGTS arc object insiame spaces. Symbol definitions are shared between vers, but instances of symbols 
arc not 

Hie VGTS lets a user view objects in any VGTs anywhere on the screen In views. Hiich view has a zoom 
factor, a window on the worid coordinates of some VGT, and screen coordinates which determine its viewport 
Although tlie SDF client can create delault views, die VG'l'S user can change them with the window manager, 
and create and destroy more of diem. Routines for the client's manipulation of voTs and views are described 
in die library manual. 

The VGTS maintains an event queue for each instance, and die VGTs associated with the given file instiince. 
Fuich VGT corresponds to an instance in die V I/O protocol. The mode bits of the instance give die kind of 
events diat will be queued. The detiiils of these functions arc defined in die library manual. 
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40.4. Pad Escape Sequences 

Unless otherwise noted, all escape sequences can come with or without the optional left bracket between 
the escape and the escape command character. Arguments to the escape command arc decimal character 
strings separated by a semicolon. The following subset of tlic ANSI standard escape sequences is decoded by 
the SUN VGTS terminal emulator: 



BELL Causes some form of audio feedback (buzzer, bell, etc.) if possible, and flashes all the views 

of the pad.. 

TAB Positions tlic cursor at next multiple of eiglit (plus one) columns, erasing characters 

between the current cui'sor position and the new position. 

FF Clears the pad. 

CR Returns the cursor to the first column of the current line. 

LF NewIJnc -- Moves the cursor down one line. If it is at the last line of the pad, all lines move 
up (scroll). 

\\S Cursor moves backwards one space. 

50 Shift Out - Select the G 1 character set. Currently ignored. 

51 Shift Out - Select the GO character scL Currently ignored. 
NUL Null ~ ignored; may be used for padding. 

DEL Delete - ignored; may be used for padding. 

ESC A CursorUp move the cursor up one line. 

ESC [/ A CursorUp - move Uic cursor up / lines. 

ESC B Newl .ine - move the cursor down, as with LF. 

ESC [/ B NcwLinc - move the cursor down ilic / lines. 

ESC C CursorForward - move the cursor forward, but do not overwrite Uic character at tlic 
current position. 

ESC (/ C CursorForward - move the cursor forward / character positions. 

ESC D Index - scroll tlie current scroll region up one line. 

ESC (/ D CursorBackward - move tlie cursor backwards / character positions. 

ESC E Next Line - move the cursor down one line, but if it is at tlie end of tlic region, scroll the 

' region up (Index). 

VSC [lie f CursorPosition - Mt)ve the cursor lo line /, column c. The lines and columns start from die 

upper \ciX, which is (1,1). Specifying /.cro or leaving an argument blank is equivalent to a 
value of 1. 'llius liSCtf alone will "home" Uie cursor to the upper left. 

ESC H Ignored, Used by some terminals to set tab stops. 

ESC [/;c H CursorPosition ~ same as F5C f. 

ESC J ClearToROS -- clear from the current cursor position to die end of die pad. 

ESC [n J Clear - if tlic argument is 2, clear the entire pad. Otherwise, clear to end of pad. 
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ESC K ClearToEOL - clear from the cursor to the end of the current line. 

ESC L Inscrtl.ine insert a line at the cursor position. All the lines below and including the 

current one arc moved down. The bottom line goes away. 

ESC [n L InscrtLine insert n lines at the cursor position. 

ESC M Reverse Index - move die scroll region down one line. The top line in the scroll region 

becomes blank. 

ESC [i M DcleteLine - delete i lines starting from the line that the cursor is on, and move all lines 

below them up. 

ESCP DcletcChar - delete the character at the cursor position, moving all the rest of the 

characters in the line to die left one column. 

ESC [/ P DelctcChar - delete / characters, starting from the one under die cursor. 

ESC @ InscrtChar move all die characters to the right of the cursor to the right one column. A 

space appears at the cursor position. 

ESC [/ @ InsertChar - Insert / characters at the cursor position. 

ESC[/m If die value of the argument is non-zero, standout mode is turned on, which will mean 

characters appear in reverse video. A zero argument resets to normal video, 

ESC [i;b r Specifics die top and bottom lines of a scroll region. This is used in die Index and 

Rcversclndex commands. 

ESC < Enter ANSI mode. Currently it is ignored, since VGTS pads are always in ANSI mode. 

ESC ) c Select GO character set Currently it is ignored. 

ESC(c . Select Gl character scL Currently it is ignored. 

The default size of a VGTS pad is 28 lines by 80 columns. 'Iliis is to be compatible with die "sun" terminal 
type of die Stiinford Unix systems. This terminal type is just a VT-100 with 28 lines, and a lew additional 
escape sequences as described above. Kor rOI*S-20, die command term VTIOO will work. On die SU-Al 
WAriTi system, die . tty sun 28 80 command can be used for display service. 



40.5. VGTS Message Interface 

'Hie use of the vgtscxec and view manager is given in the V-System Comnuwds Manual. This chapter 
describes only die internal programmer's interface. The following requests of die I/O protocol are supported: 

CRliATK.INSTANCE 

Causes a new pad to be created. The view manager will let the user decide whcrc to put die 
upper Icll corner of die pad by changing die cursor and blocking die process until the user 
clicks die mouse. The file instiuices created an; RI'lADAUI.li, WRiri'Ani.H, 
VARI ABI .V.Ji\ .OCK STREAMS. 'ITie fn-st two unspecified ficld.s of the message (if non- 
zero) are die number of lines and columns in die new pad. The filename field of the 
message is used as die name of the VGT. Usually diis is invoked only by die 
OpcnPad routine described in die VGTS chapter of die Library Manual. 

QUERYJNSTANCE 

Returns die standard values, die same as a Create Instiince reply. 

WRITE„INSTANCE ' . 
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Write the bytes to tlie pad corresponding to the file instance. Output conversions are 
performed if the appropriate '^Cooking" modes are set. 

WRrrESHORT INSTANCE • ' 

Same as WRrTE.INSTANCE. 

READ.INSTANCE 

Blocks undl some characters are entered into the pad. If there arc any characters already in 
the event queue for diis pad, they arc returned immediately. Note that since the instance is 
VARIABLE.BLOCK, un unknown number of characters can be returned, up to the 
blocksize. 

RELEASE.INSTANCE 

ThQ pad is deleted, along with any views of the pad, and storage reclaimed. 

QUERY.FILE Returns the Cooking mode bits for the pad. These arc defined in <Vgts.h> and described 
below. 

MODIFY.FILE The Cooking mode bits are set for diis pad. The structure ModifyMsg describes the format 
of this message. 

SEn'.BREAK.PROCESS 

llie break process for each instance is tlie process which will be killed when the Kill 
Program command is invoked from the View Manager. 

Switchlnput The given pad (from die fileid) is selected for input This is used in ilic SclcctPad routine. 

MouseStatusRequest 

The position of the mouse is returned immediately. This will be replaced by EvcntRcqucst 
in the future. 

MouscEventRequcst 

The position of the mouse is returned as soon as a significant event (Kcurs, as defined by 
the Mouse mode bits described in the next section, 'lliis will be subsumed by 
EvcntRcqucst in tlic future. 

EventRcquest The first item from tJic event queue is returned to ilic requester. If tlie event queue is 
empty, the requester is blocked until an event comes in for the given vg r 



40.6. Internal Organization 

The current Vet's implementation consists of the following modules: 

• Master Multiplexor. This is the only module which is operating sy^^tem dependent. Upon initiali/.ntion, 
the appropriate prix:ess structure is set up. 'ITic main loop consists of waiting for a message, dispatching 
to the appropriate routine in Uie other modules, and returning a reply. Synchronization problems are 
avoided by having the data structures accessed only in one process. 

• Terminal emulator. 'ITiis module interprets a byte stream as if it were an ANSI standard terminal. 
Printable characters arc added to text objects, and control and escape codes are mapped into the proper 
SIW manipulations. 

• Input handler. Tliere are various device-dependent input handlers. For example, a single process reads 
the keyboard and sends typed characters to die multiplexor. Another reads the mouse and tracks tlie 
cursor. 

• SDF' manipulator. 'Hiis module handles requests of applications to create, destroy, and modify 
graphical objects in structured display files. These roudnes maintiiin bounding boxes for symbols, and 
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call the appropriate redrawing routines when necessary. There is a hash table to locate items given their 
client names. 

• SDF interpreter. These are the highest level redrawing operations. The stRicturcd display files are 
visited recursively, with appropriate clipping for bounding boxes totally outside the area being redrawn. 

• Display operations. These are the graphical operations called by the SDF interpreter. 'ITiey are device 
independent, but some of the operations, like viewport clipping, are done in hardware on the IRIS 
system. 

• Drawing primitives. Tliere is one module which implements device dependent graphics primitives. On 
the SUN workstation this is a simple interface to the RastcrOp package. At this level color rectangles 
arc drawn as stipple patterns on monochromatic displays. 

• Hit detection. The stnictured display file is visited, but instead of actually drawing tlie primitives, the 
positions are checked to match the cursor's position. A list of possibly selected objects (under other 
optional constraints) is returned to the application. 

• View manager. This module provides a mode in which users can create, destroy, and modify tlie screen 
layout. Viewports can be moved rigidly, stretched, or squeezed. Views can be zoomed or panned, all 
without afFecting the applications manipulating tlie represented objects. On Llic SUN workstiition 
zooming is by powers of two, and all motions are done in one step. On the IRIS system zooming and 
moving viewports arc smooth, continuous operations. 

• Viewport primitives. These are the routines which perform the view-changing operations, invoked by 
either an application program or the user through the view manager. 

40.6.1. Executive Interface 

Since the V-System is intended to be modular, the VGTS can be used with an executive other than the 
standard one. ITie VGTS module execs . c handles the Exec Control part of the view manager command. It 
starts up new executives as new processes on the same team with the calling sequence: Ex8c( 1n, out, 
err, cmdln) where ail of the parameters are pointers to Files. These are tlic input, output, error, and 
command input files. The Hxecuiive then calls die functions SetVgtBanner(f Ho , banner) and 
SetBr9akProce3s(f lie, p1d) as commands are executed. 

40.6.2. Frame Buffer Interface 

The VGTS was intended to be ported to different graphics devices. Someday someone might actually do it, 
and then we could have some material for this section. Right now most of Uic device-dependent routines are 
in the draw, c file. 
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Simple Terminal Server 



The Simple Terminal Server(STS) is a minimal terminal agent. It does not use graphics, and it takes up less 
memory tlian the VGTS. Only one i/o stream is supported. A program that wants to do graphics direcdy on 
the SUN hardware, not mediated by the VGTS, should be run under the STS. 

The STS creates one executive. If this executive Is ever destroyed, by encountering end of file or by other 
means, it will be replaced witliin a second or so. Such a replacement can be forced by tiie sequence control-t 
X. A program running under the executive can be killed by control't k. The normal tZ and tC commands also 
work, but they can be disabled by Modify Pad requests, while the control-t sequences cannot be disabled. 



41 .1 . input Editing Facilities 

The STS provides a superset of tlie input editing facilities provided by the VGTS. All ModifyPad bits that 
are not related to the mouse work as they do under die VGTS: CR- Input, LF- Output, Echo, Lincbuffcr, 
PagcOutput, PagcOutputKnablc, and DiscardOutput 

Printing characters arc inserted at the cursor. In addition, the input buffer can be edited with Emacs-style 
text-editing commands. In the following descriptions, Cl'RL'X means striking the Control key and the x key 
simultaneously; HSC-x means striking the I^scapc key and then the x key. Killing an object means moving the 
object from the input buffer to the kill buffer. 

The STS supports the following text-editing commands: 



RETURN 


Releases the input buffer, with a ncwline appended, to tlie application. 


LINl?FUUD 


Same as Rin URN. 




Move cursor to beginning of the current screen line. 


cn<L-b 


Move cursor back one character. 


BACKSPACU 


SameasCFRL-b, 


LlilT ARROW 


Same as CI'RL-b. 


CTRL-C 


Kills the Dreak I'rocess, usually the command running in the current executive. 


CTRl.-d 


1>:lete character under the cursor. 


Cl'Rlrc 


Move cursor to the end of the current screen line. 


CT'RL-f 


Move cursor forward one character. 


RIGin' ARROW 


Same as CfRL-f. 


CrRL-g 


Abort the command. The input editor will release the input buffer, with a CTRL-g 




appended, to tlw application, which is responsible for detecting the CVRL-g and reacting 




to it 


d'RL-h 


IDelete tlie character before die cursor. 
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DEL Same as CrilL-h. 

CTRL-k ■ Kill Kill from the cursor to tlic end of tlie current line. 

CIUL-l Re-display the input buffer. 

CFRL-n Move cursor down one screen line. 

DOWN ARROW Same as Cl"RL-n. 

CTRL-p Move cursor up one screen line. 

UP ARROW Same as CTRL-p. 

CTRL-q Quote next character. Control characters arc displayed as 'tC. • 

CTRlw-c Transpose the two characters preceding die cursor. 

CTRL-u Kill the entire input buffer. 

CTRL-w Kill from the cursor to the beginning of the current word. 

CTRL-y Move die contents of killbuffer into die input buffer, inserting at die current cursor 
posidon. 

CI'RL-z Causes an End of File indication to be sent to die applicadon reading die input. This will 
terminate the Executive if no application is running. 

CTRLA Insert next character with the eighth bit set Character is displayed as '\nnn', where nnn is 
die octal representation of die character code. 

ESC-. Move cursor to the beginning of die input buffer. 

HOME SameasHSC-, . 

GSC-. Move cursor to die end of die input bu ffer. 

ESC-b Move cursor to tlie beginning of die current word. 

ESC-IUCKSI»ACP. SameasKSC-b. 

ESC-d Kill from die cursor to Uie end of die current word. 

I^SC-f Move cursor past die end of die current word. 

ESC-h Kill from Uic cursor to Uic beginning of die current word. Same as Cl'RL-w. 

ESC-DEL Same as ESC-h and CFRL-w. 

ESC-t Transpose liie two words preceding die cursor. 



41 .2. Hardware Environment 

The STS communicates with die user via die kernel console device. . If die workstiition has a framcbuffcr, 
characters are sent to die terminal emulator built into die workstation's PROM monitor; otherwise, characters 
are sent dirough serial line 0 to a character terminal. 

The attaclicd terminal or terminal emulator must understand the escape sequences sent to it by die STS for 
cureor positioning, 'llie STS currently works properly with the following tcnninal emulators and terminals: 

• Any PROM monitor terminal emulator diat supports ANSI standard escape sequences, e.g., the SMI 
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PROM monitor. 

• Cadlinc PROM monitor terminal emulator. 

• Any character terminal that supports ANSI standard escape sequences, e.g., VTIOO or Heath- 19 in 
ANSI mode. 
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Context Prefix Server 



The V-Systcm naming world Is in general a forest, with each tree corresponding to a server. Although the 
naming protocol provides a way to link this forest into a single, connected graph, we do not anticipate tliat 
enough permanent cross-linics will be set up to make the graph connected. Note that the simplest 
implementation of a cross-link requires one server to store tlic (servcr-pid, context-id) corresponding to a 
context on another server. Since server processes (and hence, server pids and context ids) may be relatively 
short lived compared to the objects they provide access to (e.g., files on non-volatile storage), such a simple 
implementation is not adequate for a permanent cross-link. 

As a partial solution to this problem, each worksuuion in the V-System contains a local name server process 
as part of its V executive. The local name server maintains a directory of local aliiuses for (server-pid, 
context-id) pairs on servers of interest. 

Furdier, since the present V kernel device server docs not provide character string names for the devices it 
implements, the local name server also performs name mapping on behalf of the device server. The directory 
of local aliases and the directory of devices are maintained as separate contexts within the name server. 



42.1 . Name Syntax 

When a client issues a Createlnstance request using the standard Open library routine, if the character 
string name begins with *[\ the request is sent to the first process responding to a 
GetP1 d(CONTEXT_SERVER , ANY_PID), ordinarily the context prefix server on the client's workstation. 

If the name does not begin with a square brucitict, the- Open routine will send the request to the client 
process's "current context" a (server-pid, context-id) pair stored in a stimdard place in tlie client's stack space 
(the "per-process arca").^^ The context prefix server is a character string name handling server that 
participates in the naming protocol described in chapter 30. including the ADI)_CONTKXT_NAIVIIi and 
DMLirrB^CONTI-'XT^NAMl"' requests. It rccogni/.cs the character as a special escape which causes the 
next component of a CSname (up to the next character or end of siring) to be interpreted in its context 0 
(DKFAUL T.CONTHXT). Context 0 is the directory of contexts maintained by tlic context prefix server, as 
mentioned above. 

The context prefix server maps tlie name in brackets (context name) to a (server-pid, context-id) pair. If the 
name consists of more than just the context name, tlie request is forwarded to the prwess designated by 
server-pid vf ith cotucxt- id placet! in the name request. The context prefix server adjusts tlie nameindex field so 
the receiving name server does not look at the context name. If the name consists only of a context, the 
context prefix server may handle the request itself, depending on tlie type of request. I'or example, 
*T}|{lJrri'.CONTi:X'l'_NAIVll-: lUiablor deletes "diablo" as the name of a context in the server. On the 
other hand, "CRI*!A'l'li_INSTANC'H [diablof would be forwarded to tlic context "(diablo]" with tlic name 
reduced to a null string. This request could be used to read tlic context directory for "[diablo]*'. 



ny "sending a request to a conlcxi," wc mean .sending the request to the wrver .specified by the (.scrvcr-pid, context-id) pnir. with the 
.specified context-id placed in the request message. Ill is procedure causes the CSname in Uie request to be inicn>rctcd in the given 
context 
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42.2. Additional Features 

The context prefix server provides a few other features which are useful in the present V-System 
environment 

An entry in the server's context directory includes space for a type indication and some flag bits, as well as 
an associated instance id and a long word of client-defined information. Space for these is also included in 
the standard context request and context reply message structures. The only bits of the entrytype Field which 
are clicnt-settable are the SESSION and LOGICAL.PID bits. The SESSION bit has no meaning to the 
context prefix server, but is used by other standard Y software to flag tlie primary name assigned to a session 
at the time it is crcated. The instance id of a session is recorded in the instanceiddxtocxox^ field. 

The LOGICAL.PID bit indicates to the context prefix server that the given server pid is to be interpreted 
as a logical, pid in the ANY_PID scope rather than an actual pid. Every time the server's name mapping 
algorithm passes through tiiis entry, it will issue a Ge tP1 d ( ) request to obtain the next pid to use. 
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— 43 — 
Team Server 



43.1 . Overview 

'ITic team server loads and keeps track of teams (usually equivalent to programs - although a program may 
consist of more than one team) running on a local host. It accepts requests to load teams and terminate teams, 
and implements a directory which can be read to find out information about all teams currently running. The 
team server also register itself with the exception server as an exception handler "of last recoui-sc." If no 
other handler registers itself for the process which incurs an exception (or its ancestors), then the loam server 
will receive the exception message and will load a post-mortem debugger to handle matters from there on, 
(Sec the command debug for a description of the debugger that is used.) 

'ITie team server resides on die "first team" on a host, i.e., it is considered to be a server which is always 
present on a host and is loaded automatically when a host's V-Systcm is booted. 



43.2. Team Loading 

Teams can be loaded from specific object code files using the library routines LoadPpog(), 
ExecProgO, or RunProgram( ) in the V library. These package up an appropriate request to Llie team 
server and take care of matters such <is setting up the inidal arguments to a team on its stack. The team server 
only creates a new team and loads down its object code from a designated open file insaince. Setting up 
parameters and setting initial execution priority and stuck size is left to the team load requestor in order to 
allow control over the order of events. This is necessary for programs such as debuggers which wish to allow 
users to set breakpoints and examine the code before a team actually starts to run. 

Load requests to die team server also specify who the "owner" of a team is. Teams are destroyed if their, 
owner process goes away (siimc semantics as for prcx;csses created by other processes). Teams can optionally 
be specified to be owned by the team server itself, thus pennitting them to outlive tlicir load requestors. 



43.3. Team Termination 

Teams can terminate by either having their root process destroyed or by sending a termination icquest to 
the team server (the library routine exit() docs this). The latter fonn also causes die team server to destroy 
the team's root process; but in addition it allows die team server to immediately update its record of the state 
of currently nmning teams. The server uses a Umer process to periodically query die state of all teams which 
die server Uiinks arc still running and remove server entries for tliosc that have unexpectedly gone away. 



43.4. Status of Running Teams 

The standard context directory listing protocol (sec section 30,7) can be used to obtain information on all 
teams which are currendy running under die team server. To obtain information on a specific team only, an 
NRHAD^DI^SCRIPrOR request can be made. The team of interest is specified by setting tlie request 
message's conicxtid field to die team's root process id; the CSname in the message has no significance. 
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43.5. Remote Execution 

Tlic implementation of the team server and team-loading library routines is such tiiat load requests can be 
made to both local and remote team servers, thus allowing for transparent remote execution of V programs. 
In order to assure die priority of local requests the team server keeps track of the stale of the local host with 
respect to things such as wiicther someone is logged in or not, how many applications are running, etc. 'lliis 
state is used to determine whether or not a remote load request will be accepted or not 

Currently the only state information maintained by the team server is whether or not someone has logged 
into the host Also, the current policy with respect to remote execution is to accept all requests regardless of 
the local host's state. 

Tlie team server also interacts with die service server in order to globally register the current state of its host 
An update of tlic host's status is sent whenever its state changes and whenever the service server requests such 
an update (c.g. when the service server first starts up and needs to acquire the current state of ail hosts in the 
system). 
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Part IV: 
Kernel 
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— 44 — 
Kernel Overview 



The V kernel is a message- based distributed kernel that implements a program environment of many small 
processes communicating by messages. This program environment is implemented on one or more 
workstations connected by a local. network. The kernel was designed to provide an efficient, real-time prixrcss 
model on which to build sophisticated single-user systems, multi-user systems^ network-accessed servers and 
dedicated real-time applications. These applications may be distributed over one or more network nodes or 
workstiitions. The kernel is also designed to be reasonably portable over a large class of machines and local 
networks.^* This manual describes the V kernel: its operations, die mechanics of using the kernel, the 
kernel internal structure, and how to maintain the kernel, namely adding kernel operations and devices. 
Kernel operations can be broadly divided into three categories: pr(x:ess and memory management, 
interprocess communication, and device management. 'ITic following sections of tliis chapter provide an 
overview of die kernel Facilities and Llieir intended use. 



44.1. Process and Memory Management 

Tlic kernel manages memory as entities called team sfmces, which correspond to an address space or context 
on the workstation. For example, on die SUN workstation a team space is a context as implemented by the 
hardware memory management. Operations are provided for creating team spaces, querying tlie size of a 
team space, and setting the si/e of the team space. Team spaces disappear when tlie last process contained in 
that space is destroyed, so there is no explicit operation for destroying a team. 

A team space is endrely contained on a single workstation. On some machines, the kernel is actually part of 
the team address space but this fact is transparent to the program. For instance, on the SUN pr(x:cssor board, 
segments 0 and 1 in every context are kernel space, but protection bits are set to prevent access except in 
supervisor mode. 

A process is a logical activity tliat sequentially executes instructions. Associated with each process is a 
priority, state, a team space and a suick. The process priority dictiUes tlie preference given to this process with 
respect to pr(x:essor allocation. The highest priority ready process is allocated Uie processor. (0 is the highest 
priority.) The stale is essentially tlie machine state of the processor lor tliat process. The team space is the 
area of memory to which die process has direct access. The stack is tlic local memory area contained in the 
team space that the pnxicss uses for kKal workspace, pr(x:edure linkage and return, and the like. All processes 
wiUi the same team space are said to be on the same team. 

The kerne! provides support for a per-process area by associating a location and value with each process. 
Whenever a process is activated, tlie kernel stores its per-pr(x:ess value in its per-process location. By 
convention, each process on ;i team uses the siime per-process location, and each per-process value is a pointer 
to a slimdard per-process data area within tlie j)roccss's stiick space. 

Processes can be dynamically created and destroyed. When a process is created, it is assigned a unique 
process identifier that is used subsequently to specify that process. Also, it is created as part of die same team 
as its creator. A process is created in tlie initial state of awaiting- reply from Its creating process. (See next 
section on interprocess communication.) When a process is destroyed, all the prtxjcsses created by this 



Currontiy. it Invs only been implctncnlcd on the Motorola 68000-bnscd SUN work.stnlions connccicd l^y J Megabit or LO Megabit 
Ethernet An implementation on a VAX 11/750 is under way. 
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process arc also destroyed. 



44.2. interprocess Communication 

Interprocess conimunication is provided in two forms by the kernel. First, processes may send, receive, 
reply to, and forward fixed-length synchronous messages. A process sending a mcssiige is suspended awaiting 
reply until ilie message it sent has been received and replied to by the receiving process. Messages are 
currently 8 fliU words, where a full word is defined to be the maximum of the space required for a general 
machine pointer and the space required for a "natural" machine precision integer (32 bits on the MC68000' 
based SUN workstation). 

Second, a process can pass access to a single segment in its team space to the recipient of its message. The 
recipient process can access this segment for reading or writing, depending on the access specified by the 
sender, while the process is awaiting reply from the rccipicnL By convention, the segment start address and 
size are specified by the last two words of the message by which access to the segment was given. The 
presence of a segment and its access modes arc specified in the first byte of the message. 

A process tliat is blocked awaiting reply from a process that is subsequently destroyed is unblocked with an 
indication tliat tiie receiver of the message does not exist 



44.3, Naming 

I'hc kernel implements a low-level naming service that provides efficient access to server processes that 
implement higher level functions. A pnxrcss can register its process identifier as corresponding to a particular 
logical process identifier. Processes can then query the kernel as to tlie process identifier corresponding to a 
specified logical process identifier. Registration of die logical to real process identifier can be specified as 
\ocs\\ to a workstation, remote, or botli. 



44.4. Time Management 

rhc kernel provides operations for reading the time, setting tlic time, delaying for a time period, and 
unblocking a delaying process. 



44,5. Device Management 

IDevices managed by the kernel are currently all accessed through tlie device server pseudo-process inside 
the kernel. Operations arc performed by sending ni<»sages to tlie device server. The protocol used in these 
messages is the Verex I/O protocol^ which is described in the V-Sysiem Servers Manual. 

Devices that can be controlled without special kernel support am be handled directly by processes. Special 
devices that require kernel support but do not fit the I/O model can be handled by adding new kernel 
operations. 



44.6. Initialization 

After the kernel hi\s completed its Internal initialization, it creates an inidal team space and an initial 
process on this team. It tissumes there is a descriptor following it in memory that describes the code and data 
segments plus die starting instruction for this initial team. Enough physical memory is assigned to tlic team to 



"nislributcd I/O using an Objcct-Dascd I'rotocor by David R. Chcrilon, UDC Computer Science Technical report 81-1. 
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accommodate its code and data segments. 



44.7. Distributed Operation 

The kernel supports transparent communication among several workstations rimning the V kernel. 
Processes on different workstations may send and receive messages and access segments as though all 
processes were executing on the same machine. This mt)de of operation requires a high-speed local network 
connecting the workstations. Most kernel operations may be performed transparently on non-local processes. 



44.8. Application-Level Model 

Using the kernel well requires understanding the model of processes and messages tliat the kernel provides, 
and how they are intended to be used. Processes represent logical activities in the application. They are 
intended to be sufficiently inexpensive to allow tiic use of multiple processes to achieve tlie desired level of 
concurrency in die applicadon. The process identifier is intended to serve as a loose form of capafjility or 
"ticket." Possession of a process identifier is sufficient to allow the pnxrcss to send a message to Uic specified 
prtx;cs.s. Also, because there is no notification facility on (he destruction of a process, resources allocated to a 
process should be associated with its prwcss identifier if they are to be reclaimed. The application can then 
use "lazy reclamation" of resources by "garbage collecting" resources ass(x:iated with invalid process 
identifiers. However, a process may block until another is destroyed using eidicr UccciveSpecific or Send. 

Hie synchronous message sending is intended to Implement communication between pnxresses tliat looks 
to the sender essentially like procedure calls. That is, tlie Send request message sends the paramctci-s of the 
procedure and tlie reply message returns the rraulLs, 'Hie greater flexibility provided to Uic receiver allows 
sophisticated scheduling of message handling and replies. Ikcause message sending is totally synchronous, 
concurrency must be achieved by multiple processes. 

The segment access operations follow the procedure paradigm in being used primarily to access what are 
logically "call-by-refercnce" parameters. The argument for providing cxacdy one segment is tliat at least one 
is needed, and one is sulTicicnt for die dominant activity, namely file access. It is expensive and difficult to 
provide arbitrarily many segments - having just one segment allows a simpler and more efficient 
implementation. Finatly, multiple segments can be linearized to one, so no functionality is lost with Uiis 
restriction. 

'ITiere is no form of asynchronous communication between processes. It is intended that process destruction 
be used for asynchronously interrupting die activity of a pr(x:ess. 

Teams arc intended to provide fine-grain sharing of code and inexpensive sharing of data between 
cooperating processes. 'I'hcy separate the idea of program, executable unit, and address space from diat of 
process. 
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— 45 — 
Kernel Operations 



The operations provided by the V kernel can be divided into three classes: kernel ti'aps, kernel process 
operations, and kernel device operations. 

TItc most basic kernel operations, including Send( ), are implemented as kernel traps. These operations 
are invoked by executing a trap or system call instruction which invokes the kernel. A number of secondary 
operations are implemented by a pseudo-process running in the kernel, called the kernel process. Such 
operations arc invoked by sending to the kernel process's pid. Finally, operations on kernel-implemented 
devices are provided by a second pseudo-process, called the kernel device server. Such operations are 
invoked by sending mcssjiges to tlie device server's pid, using the standard .V-System I/O protocol. 

The kernel traps include: 

ForwardO GetPid() MoveFrom() 

MoveTo() ReceiveSpecif ic( ) Recei v8WithSegment( ) 

ReplyWi thSegment( ) . RereadMsg() Send() 

'ITie kernel process operations include: 

Cp9atePpocess( ) CreateTdain( ) D«Tay() 

OestroyProcess( ) GetTlmeO QueryProcessState( ) 

SetPidO SetTeamPriority( ) SetTeaniSi2e( ) 

SetTimeO Wakeup() Wri teProc9SsState( ) 

'Hiese functions are documented fully in the V-Sysiem Program Pjivironmeiu Manual. Other kernel 
operations described tlicrc, such iis Recei ve( ), Reply ( ), Val 1dP1d( ), etc., arc implemented as library 
functions using tlie basic operations listed above. 
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Exceptions and Kernel Exception Handling 



The V kernel handles exceptions (such as illegal instruction or bus error traps) by forcing the erroneous 
process to send a message to tl\e exception ^mer containing the details of the error. The exception server is a 
process that has registered as the EXCEFI'ION.SHRVER with die kernel using Setl'id. If no exception 
server exists, die message is sent back to the process diat caused the error, blocking it permanently. In either 
case, oUier processes in the system can continue to rim. 

The message from the exccpdon-incurring process to die exception server appears as a normal message and 
can be received by die standard message primitives. After receiving die message, the exception server can 
read die faulting process's state using either die kernel primitive QucryProcessSiatc or the library function 
ReadProccssStatc. In tlic Sun implementation of the kernel, the registers in the suite record reflect the 
processor state at die time of the exception, unless it occurred while mnning in tlie kernel. In diat case, the 
program counter and status register returned arc those diat were saved at tlie time die kernel trap was taken. 
The other registers reflect die state at the time of die exception. The correct program counter and status 
register contents can always be obtained from die exception message. 

The message also provides read and write access to die segment consisting of die entire team address space 
of die exception-incurring process. This provides debuggers and exception servers with complete access to 
die code and data of die process. 

The fomiat of die exception me^gc is given by die ExceptionMessage struct in <Vcxccptions,h> together 
with manifest consumt definitions for die type of exception. The message format for the Motorola 68000 is 
given below. 



buscrrortypc Additional information on die cause of the error, if type is equal to BUS^ERROR. 



requcstcode 



EXCiynON.REQUHST 



type 



Type of exception. This is encoded as the address of the MC68000 oxccption vector that 
was taken. 



code 



In die ease of address errors and bus errors, this contains a code returned by die processor 
to identify die type of memory reference diat caused tlic exception. Only the low order 5 
bits of diis word are valid; die others should be masked off. For otiier types of exceptions, 
th is word contains zero. 



accaddr 



The access address in die case of address or bus errors, otherwise zero. 



instruction 



The instruction register in die case of address or bus errors, otherwise zero. This should be 
die first word of die instruction dial caused die error. 



status 



segment 



crrpc 



segmenLsi/e 



'Yhc status register. 
The program counter. 

Starting address of die team's address space. Currendy at 0x10000 on tlie SUN worksuuion 
because the kernel uses the first two segments. 

Number of bytes in die team's address space. 
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Sec tlic Motorola MC68000 User's Manual for a description of the types of exceptions possible and the 
meaning of the information returned by die processor and passed on in tiiese exception messages. 

Exceptions arc always blamed on the currently active process, even if they occur inside the kernel. For 
instance, it is possible for an exception inside the kernel to be caused by an invalid pointer passed by a process 
when invoking a kernel operation. However, it is also possible for exceptions to be caused by bugs in the 
kernel itself, though diis is unlikely unless an experimental version of the kernel is being tested,-''^ A 
standard exception server process has been implemented and is described in die V-Sysiem Servers Manual. 



Hie woRit cose Ls wlicn (he ciccption us caused by a bug in a kernel intcrnipl handler, since in Uia( case there would be no relation 
between lite currently active process and the code Uinl caused the exception; however, in (his case, the bug is likely to cnish the processor 
anyway. 
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— 47 — 

Performance 



Two measures of performance for the kernel arc die speed of various operations and space requirements. 
For a detailed account of the performance of the V kernel, we refer the reader to The Distributed V Kernel 
and Its Performance on Diskless Workstations, by David R. Chcriton and Willy ZwaencpocI, in Proceedings 
of the 9th Symposium on Operating System Principles, October 1983 (also available as Technical Report 
STAN-CS-83-973, Computer Science Department, Sumford University). 



47.1 . Space Requirements 

Hie space requirements are dependent on tlic machine, die number and complexity of devices supported, 
and the maximum number of prwesscs, teams and devices configured. Table 47-1 gives the code segment 
si/e for die kernel configured to support distributed operation on the SUN workstation with support for 
console device, serial interfaces, Rdiernet interface and a mouse pointing device. The Uiblc also gives the unit 
space cost of a process descriptor and a team dCsScriptor, and die total space requirements for a kernel 
configured with a maximum of 64 processes, 16 teams and 16 device descriptors. All measurements arc given 
in bytes. 

Table 47-1: SUN Workstation Kernel Memory Requirements 

Component Si/c in bvtes 
code segment 31836 
process descriptor 202 
team descriptor 18 
device descriptor 44 
totol 47990 



47.2. Kernel Operation Times 

Table 47-2 gives die limes lor various sequences of kernel operations on die SUN workstation using a 10 
Mcgalicrtz Motorola 68000 processor. The Umcs for sequences of operations arc given instead of times Ibr 
individual operations to give a better indication of die kernel overhead for higher-level operations. Vot 
instance, die Scnd-Reccivc-MoveKrom-Reply sequence is indicative of die dmc to perform a file read 
operation using die I/O protocol. These sequences arc also easier to time in some cases dian individual 
component operations. 

Table 47-2: SUN Workstation Times for Kernel Operations (in millisa-onds) 

local remote 

GctTimc 0.06 Not Applicable 

Scnd-Receive-Reply<0 bytes) 0.77 2.54 

Send-Reccive-Reply(512 bytes) 1.31 5.56 

The table is not intended to be complete but simply indicative of performance. The Send-Reccive- Reply time 
is indicative of die inteiprocess communication time using the kernel. The column labeled "remote" gives the 
Scnd-Rcccive- Reply time between two prwcsses resident on diflcrcnt workstiitions. The GctTimc lime is 
indicative of die cost of a trivial kernel operation. All other kernel operations can be expected to be faster 
than die Scnd-Reccive-Reply sequence. 
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Another measure of interest is the speed at which packets can be read and written over the Ktiiernct with 
the overhead of sending read and write requests to tiic kernel device server to access tlie network. Table 
47-3 gives pcrfonnance figures for the kci-nel running on the SUN workstation connected to a 3 Megabit 
Ethernet. 



Similar throughput figures for a stand-alone Alto arc 4, 120 and 140 Kbytes per sec (approximately). 

On the input side, with one SUN writing as fast as possible to another, 10000 packets of 1024 bytes can be 
received in 5.S9 seconds with 0 packets lost, yielding a throughput of about 170 Kbytes per second, which is 
about 40% of tlic bandwidth of the ncL However, for some unknown reason, packets are dropped as the 
packet size becomes smaller. 



47.3. interrupt Disable Time 

'ITie interrupt disable time for the kernel is essentially tlie maximum of the time required to insert a record 
in a ordered queue (the ready queue) and the time to load the processor with the state of a new process. 
Although the fonner is dependent on tlie maximum number of ready priKcsscs, it is typically very small. For 
example, on die SUN workst^ition, adding a lowest priority process to the ready queue when 32 processes are 
ready to execute is estimated to result in an interrupt disable dmc of 164 microseconds. Under normal 
circumstances, an intemipt disable Ume of about 30 microseconds can be expected. 



Table 47-3; SUN Workstation Fthemet Output 



Packet Si/e in bvtes Packets ncr sec 



ITiroughout in Kbvtcs/sec 



16 2200 
512 360 
1024 170 



35 
180 
170 
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Kernel Internal Structure 



Tlie kernel is implemented as a simple monitor. It executes logically in its own address space in supervisor 
mode with its own code, data and stack. It is invoked by trap operations and interrupts. When a process 
executes a kernel operation or an interrupt trap is taken, the kernel executes on the kernel stack. 

48.1. Teams 

Each team is represented by a team descriptor record (TD) that describes the team space, records the root 
process of the team, user associated with Uic team, team priority level, etc. A machine-dependent portion of 
the team descriptor describes the team's memory space. 



48.2. Processes 

For each process, the kernel maintains a process descriptor record (PD) tiiat contains tlic process stiUc and 
sundry information about the process. When a process is running, a variable Active poinLs at tlie process 
descriptor of the currently active process. 

48.3. Kernel Synchronization 

The kernel is synchronized internally by a combination of scheduling conventions and interrupt 
masking. The conventions arc: 

• l^oth kernel trap-invoked and intermpt-invokcd operations only add or remove processes frofn ilic list 
of ready processes, 'lliey cannot bl(x;k a prcx'c&s in the middle of a kernel operation. The clock 
interrupt routine that may change die stale of a process blocked on a remote or honcxistenL pnxrcss only 
docs s*) if it did not interrupt a kernel operation. Similarly, etlicrnct interrupts are disabled during the 
execution of a kernel operation to prevent remote intcrkernel packets from interfering with the 
execution of the kernel operation. 

• A process switch occurs at the end of a kernel operation if the active or invoking prix'css is no longer the 
hi^est priority ready process. The process switch occurs at the point of return from tlie kernel trap 
handler after executing the kernel trap. 

• A process switch occurs at the end of the execution of an interrupt service routine if the active process is 
no longer tlie highest priority ready process ANH the interrupt servicing did not interrupt a kernel 
operation. Hiat is. a prwess switch cannot occur in the middle of a kernel operation due to an interrupt 
even though tlie interrupt can otherwise be serviced. 

'ITie net result is that a process executes a kernel operation indivisibly with respect to other processes until it 
blocks. However, the highest priority ready process is alUxiated tlie processor whenever the processor is not in 
supervisor state. Masking of interrupts is used at crucial points in manipulation of tlie ready queues and 
process switching so that interrupt routines do not interfere. 
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48.4. interrupt Routines 

Interrupts arc handled by first invoking a simple assembly language routine that saves some registers and 
then calls a C procedure assix:iatcd with tliat intermpt level, possibly passing some arguments. A macro 
"Calljnthandlcr" generates tlic required assembly language routines that call the C procedure it is passed as 
an argument. Interrupt- invoked routines are assumed to be short and do little in interacting with processes 
otlicr than possibly readying a process. 



48.5. Kernel Traps 

An assembly- language module handles trap instructions, invoking the specified kernel operation and 
handling die return. On a trap, it moves the arguments onto the kernel stack and calls the specified kernel 
operation as a C function. On return, it moves die return value back to the process's stack if necessary and 
checks for a higher priority ready process. If there is one, it switches to the highest priority process. If the 
active process is sdll the highest priority ready process, the acdve process is allowed to continue execution at 
the instrucdon after the trap instrucdon in its code segment 



48.6. Kernel Process 

If die specified pid fails to validate on a Send, die Send routine checks whether it is die pid of the kernel 
process or of the device server process. If the kernel process pid was specified. Send calls die ScndKcrnei 
roudnc to perform die requested operation. Thus, tlic "kernel process" code is executed by die process 
invoking die operation, not a separate process running in die kemeU The message format and die request 
codes die kernel priKCss supports can be found in <VcnvironJi>. The kernel process idendfier is a global 
variable, KcmeLProcess.Pid, set at die beginning of each team's execution. 



48.7. Device Server Process 

A Send to die device server process rcsulte in Send calling the SendDcvicc routine to perform the requested 
operation. Thus, the device server code is executed by the process invoking die operation, not a separate 
process nmning in the kernel. A process diat is forwarded to the device server has its finish-up flmction (see 
below) set to SendlDevice, and is readied, so diac it will begin executing in SendDcvice as soon as it reaches 
die head t)rdie ready queue; 

48.8. Process Switcliing 

All process switches occur in the macro fijnction Switch diat switches from die currenUy active process to 
die process at tlic head of die ready queue. Kach process is created with its state inidalizcd to start it at die 
inidal prognim counter In its team space when it is readied. Switch relies on dicre always being a ready 
process to execute (i.e. non-empty ready queue). 'Hiis is guaranteed by die presence of an *'idlc" process diat 
is always ready and executes the processor stop or idle instruction. 

Intcrrupt-invokcd routines execute as "involuntiiry" asynchronous function calls made by die currently 
acdve process and dius can also use Switch. 

Process switches always occur upon exit from die kernel, never in die middle of a kernel roudnc. Tlius, the 
kernel only requires one stack, not a separate kernel stack for each process. If dierc will sUll be some work to 
be done on a kernel operaUon when a process is unblocked, llie kernel roudnc diat blocks it sets \hQjinish-up 
function field in die process's state record. If diis field is non-/ero when a process is unblocked, the specified" 
function is called before die process exits die kernel. A finish-up function can block die pnK'CSS again and set 
another finish-up function if necessary. 
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Note: The kernel implementation described so far should support a number of different types of kernels. 
Also, this basis of trap and interrupt handling plus process switching, device management, and memory 
management represents most of the- machine-dependent code in the kernel. 



48.9. Processor Allocation 

The strict priority-based processor allocation is implemented efficiendy by maintaining a queue of ready 
processes in order of priority, highest priority fu-st. A state field in die process descriptor indicates the process 
is ready (and thus in tliis list) or else the state in which it is bUx:ked. Process switching incorporating this 
priority based allocation and ready queue management is implemented by two (internal) primitives. 

Removercady(pd) Remove the specified process from the ready queue. The active process continues to 
execute until it exits the kernel even if it has just removed itself from the ready queue. 

Addready(pd) Add the specified process (descriptor) to Uic ready queue in order of priority, after all 
processes of tlie same priority as tliis process. 



48.10. Process Creation and Destruction 

Unused process descriptors are maintained in a queue. When a process is created, a process descriptor is 
removed from die queue, assigned a process identifier, and initialized to die specified priority, awaiting reply 
state* creator's team, etc. 

When a process is destroyed, it is removed from any system queues, such as the ready queue or any message 
queues (one major use of the PD state field is indicating presence in a queue), the process identifier is 
invalidated and all its descendants are destroyed similarly. Ilie resulting free process descriptors arc added to 
the end of the queue of unused process descriptors. ITie ckx:k interrupt routine is charged with checking for 
processes blocked on non-existent processes (one per clock interrupt) so the process destruction mechanism 
need not worry about this. 



48.1 1 . Message Primitives 

While a messiige Implementation nomially requires independent kernel mcssiigc buffci-s, the semantics ot" 
the messiigc primitives in this kernel allow the ines.sage buftcr to be sUitically associated with die process 
descriptor so we include it as part of the siime C stmct. Thus, a messijge is queued at a receiver by queuing 
Uie prt)ccss descriptor of the sender, saving on extra space for sender identifier, etc. plus time to map to die 
PO of die sender for unblocking it. 

Sending to Uic kernel device server or to the kernel process is handled by checking die pid of Send to see if 
it specifics die kernel device server or die kernel process when Uie pid fails to validate as a real process. The 
SendDevicc or SendKerncl routine is then called directly to implement die kernel device server or kernel 
process. 



48.1 2. Time Primitives 

Processes delaying using Delay arc maintained in a queue starting at Oelayq^head ordered by increasing 
time to unblock. The time before a pr(x:ess unbUwks is stored in its blocked_on field in terms of the number 
of clock Interrupts it must delay after die process before it in die queue is unblocked. 
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48.13. Distributed Operation 

The process identifier contains an indication of the host in its 16 high-order bits. When an operation is 
invoked that specifies a process identifier tliat Fails to validate locally, it is assumed to be a reinotc process. 
The operation tiien invokes a "nonlocal" version of the operation that formats a network message and 
transmits it to tlie workstation host specified by the process identifier. The primary interface to the network is 
tlic WriteKcmelPackct routine. 

In tiic case of GctPid, a message is broadcast requesting the logical id to pid mapping. 

When a process is blocked sending to a remote process, the message is retransmitted periodically by the 
clock interrupt routine until a reply is received. Hie Send fails after some number of retransmissions if no 
"breath of life'* packets have been received from the remote host in that time. 

A message received on a workstation from a remote process causes a process descriptor to be alUx:ated to 
store the message and make it appear as a local message to die rest of tlie kernel. A process descriptor used in 
this fashion is called an alien. Aliens are destroyed an appropriate time interval after the Reply message is 
sent. (11iis interval is 0 for idempotcnt requests.) 

'Hiis description is fiir from complete. For a fully deuiilcd discussion of the intcrkcrncl protocol, sec The 
Distributed V Kenicl and Its Perfonnance on Diskless Workstations, by David K. Cheriton and Willy 
Zwaenepoel, in Proceedings of the 9th Symposium on Operating System Principles, October 1983 (also 
available as Technical Report SrAN-CS-83-973, Computer Science Department, Stiuiford University). 
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Kernel Modification and Maintenance 



The type of kernel modifications anticipated include: changing the maximum number of processes, teams, 
or devices allowed, adding or removing kernel operations, and adding support for new devices. 

49. Kernel Configuration Parameters 

The machine-dependent file config.h contains the kernel configuration parameters. 

MAX.PROCESSES 

Maximum number of processes, which must be a power of 2. 

MAX_TF.AMS Max. number of teams, currently at most 16 on die SUN workstation. 

MAXJDBVICHS Max„ number of device instances, which must be a power of 2. 

ROOT.PRIORITY 

Priority of root process of first team. 

INIT.STAGK Size of initial stack for root process of first team. 

11ie kernel can bo reconfigured with respect to these parameters by clianging their definitions in configJi 
within tile constraints mentioned above and recompiling the kernel. 



49.2. Adding New Device Support 

Supporting a new device using tlie kernel device manager requires writing device-specific initiali/.ation, 
read, write, release, modify and intcrrupt-handUng routines and adding an enU7 for the device in the 
DcviceCreationTablc defined in cunjig.c. There is nonnally a header file for tlie new device tliat defines its 
device type for Uiis table plus other device-specific infonnalion required by users ofUie device. The existing 
devices and kernel operations arc useful models from which to work. 



49.3. Adding Kernel Operations 

Adding a kernel operation requires writing the C routines tliat implement the operation, adding an entry 
for it to the kernel trap table, kcrnclops, defined in intp.c and possibly adding a .v/w/; for tliis call to the C 
environment library for the kernel calls. Adding a new operation to Uie kernel process requires defining a 
new request code in <Vcnviron,h>, handling this request code in Hie main loop of the kernel process and 
writing the appropriate code for handling Uie request. Operations that must be available to remote processes 
should be implemented as kernel process operations ratlier Uian kernel traps. 

Certain restrictions apply to kernel operations. They may not execute trap operations or call upon services 
provided by other processes ouLsidc the kernel. However, they can use other routines already available inside 
the kernel. Kernel operations are passed exactly 5 arguments and allow one return value. A kernel operation 
cannot take a variable number of arguincnts unless Uie number is encoded in tlie vii lues passed. Operations 
tliat access any data modified by intcrrupt-invoked routines need to mask interrupts if lhcre is any possibility 
of interference. Finally, operations tliat block or unblock proceSvSes should use the internal primidves 
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Part V: 
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— Appendix A — 
C Programming Style 



llicrc has been an effort to use a consistent style in V for writing C programs. The style and the uniformity 
it encourages arc motivated by the desire for readability and mainiainability of software. Although style is to 
a large extent a matter of individual Uistc, the following describes some general practices with which most of 
us agree. 



A.1 . General Format 

Recognizing that software is written to be read by other programmers and only incidentally by compilers, 
the general format follows principles cstiiblishcd in formatting general Bnglish documents. Take a few more 
seconds to make tilings more readable; it is time well spent. 

First, software is written to be printed on standard size (8 by 11) paper. This means avoiding lines longer 
than about 80 columns. In general, Clierc is one sUttcmcnt or declaration per line. 

As with odier documents, judicious use of white space with short lines and blank lines is encouraged. In 
pardcular, 

1. At least 2 blank lines between individual procedures. 

2. Blank lines surround "large" comments. 

3. Blank lines around any group of statements. 

4. Blank lines annrnd cases of a switch statement. 



A.2. Names 

Names arc chosen when possible to indicate Uicir semantics and to read well in use, for example: 
1f ( 6et0evice(E!therInstance) <*- NULL ) return( NOT.FOUNO ); 

Words should be spelled out, not shortened. A good test is to read your code aloud. You should be able to 
communicate it over a telephone easily, without i-csorting to spelling out abbreviations. 

In addition, character case conventions are used to improve readability and suggest the scope and type of 
the name. Global variables, procedures, strucLs, unions, typedefs, and macros all begin with a capital letter, 
and are logically capitalized thereafter (e.g. MalnHashTable). A global variable is one deruied outside a 
procedure, even though it may not be exported Iroin the llle, or an external variable. The motivation for 
treating macros in tliis way is that lliey may tlicn be changed to procedure calls without renaming. 

Manifcist constants cither follow tlie above convention (since they are essentially macros with no 
parametei^) or else arc fully capitalized with use of die underscore to separate components of tlie name. E.g. 
WRITE.INSTANCE. 

Local variables begin with a lower-case letter, but are either logically capitalized Lliereaiter (e.g. b1 tWi dth, 
power. maxSumOf Squares) or else totally lower case. Fields within stmctures or unions are treated in ttiis 
manner also. 
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Local variiiblcs of limited scope arc often declared as register. If tlicy are used very often inside inner loops. 
U is not only more efficient, but usually more readable, to put a pointer to an array of complicated structures 
(a common occurrence in object-oriented' programming) into a register variable with a short name. For 
example, 

register struct Descriptor *p - Descr1ptorTab1d->-obJectIndex; 
p->count "0; 
Initial 1ze(p~>start) ; 
P'>usage ■ p->defau1t; 
p*'>1ength ■ p'>end - p->start; 

instead of the inefficient and cluttered: 

OescriptorTablaCobjsctlndex]. count ■ 0; 
Initial ize(0escr1ptorTableCobjectIndex]. start) ; 

OescriptorTabl eCobject Index ] . usage > DescriptorTableCobJectlndex] .def aul t: 
Oescr ip tor Tab 1e[obj act Index]. length > OescriptorTabl eCobject Index]. end 
- DescriptorTableCobJectlndex]. start: 



A.3, Comments 

There are generally two types of comments: block-style comments, and on-thc-linc comments or remarks. 
Multi-line, block-style comments have the /* and */ appearing on lines by themselves, and die body of the 
comment starting with a properly aligned *. The comment should usually be surrounded by blank lines as 
well. Thus it is easy to add/delete first and last lines, and it is Ciisier to detect the common error of omitting 
tlic */ and thus including ail code up to and including the next */ in a comment. 

/• 

* this is the first line of a multi-line coimnent, 

* this is another line 

* the last line of text 
•/ 

On-line comments or remarks are used to detail declarations, to explain single lines of code, and for brief 
(i.e. ono line) block-style descriptive comments. 

Procedures are preceded by block-style comments, explaining tlicir (abstract) function in terms t)f their 
parameters, results, and side eficcts. Note that tlie parameter declarations are indented, nut fiushed left. 

SystamCode EnetCheckRequest( req ) 
register loRequest *req: 

C 

/• 

* Check that the read or write request has a legitimate buffer, etc. 
•/ 

register unsigned count; 
register SystemCode r; 

/• Check length •/ 
count ■ req->bytecount; 

if( count <- lO.MSG.BUFFER ) return( OK ); 

req->bytecount "0; /<* To be left zero if a check fails */ 

if( count > ENET.MAX.PACKET ) 
{ 

r - BAO.BYTE.COUNT; 

} 

else 

{ 

/• 

* Make sure data pointer is valid. 

* Check that on a word boundary and not in the kernel area. 
•/ 
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if( ( ICheckUserPoinit8r( r8q->buf f erPointer) ) || 

(Active->t9am->teamSpaca. S128 < (req->bufferPo1nter + count)) || 
({int.) req->buf farPointer) & 1 ) 

{ 

r • »A0 BUFFER: 

} 

else 
C 

req->bytecount • count: 
r - OK; 

} 

> 

return( r ); 

} 

A.4. Indenting 

The above example shows many of the indenting rules. Braces ( and ) appear alone on a lino, and 
arc indented two spaces from the statement tiiey arc to contain. 'ITic body is indented two more spaces from 
tlie braces (for a total of four spaces), el se s and el se if s line up with Uicir dominating if statement (to 
avoid marching off to die right, and to reflect the semantics of tiic statement). 

If ( (X - y) 0 ) 

{ 

flag • 1; 

pr1ntf(* the value was zero 

} . 
else if ( y 1 ) 

C 

sw.itch ( today ) 
C 

case Thursday: 
nag - 2; 
ThursdayActionO ; 
break: 

case Friday: 

nag - 3: . 
FridayAct1on() ; 
break; 

default: 

OtherOayActlonO : 

} 

} 

else 

pr1ntf(" y had the wrong value "); 

A.5. File Contents 

ImIc contents arc arranged as follows. 

1. initial descriptive commcjit (sec example below) contains brief descriptive abstract of contents. Some 
programmers add one or more of the following as well: 

a. a list of all defined procedures in their defined order, or alphabetically. 

b, list of recent and major modifications in reverse chronological order with indication (initials) of 
who made the change. ""' ■' 

2. included files (use relative paUi names whenever possible) 
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3. external defmiciuns (imports and exports) 

4. external and forward function declarations 

5. constant declaradons 

6. macro definitions 

7. type definitions 

8. global variable declaradons (use static declarations whenever possible, and group variables with tlie 
functions that use dicm) 

9. procedure and fiinction defmitiohs 
Here is the beginning of a file as an example. 

* Distributed V Kernel - Copyright (c) 1982 by David Cheriton, Willy Zwaenepoel 

« Kernel Ethernet driver 
•/ 

#1nclude ./. ./I ibc/include/Vethernet.h" 
^include "interrupt. h" 
/^include "ethernet.h" 
^include "ikc.h" 
^include ./ffli/dm.h" 

/• Imports •/ 
extern Process 'MapjidO; 
extern SystamCode NotSupported() ; 
extern Oevicelnstance *GetOevice( } : 

/• Exports */ 

extern SystemCode EnetCreate() : 

extern SystemCode EnetRead(); 

extern SystemCode EnetWriteQ; 

extern SystemCode EnetQuery(); 

extern SystemCode EnetChecl(Request( ) ; 

extern SystemCode EnetReadPaclcet( ) ; 

extern SystemCode EnetPowerup( ) ; 



unsicjned char EnetHostNumber ; /* physical etharnet address */ 

Instanceld Ethernetlnstance; /* Instance id for Ethernet */ 

int EnetReceiveMask; /* addresses to listen for */ 

short EnetStatus; I* Current status settings */ 

int EnetFIFOempty: /* FIFO was emptied by last read */ 

Int EnetCol 1 Isions ■ 0; /* Number of collision errors */ 

int EnetOverf lows ■ 0: /* Queue overflow errors */ 

int EnetCRCerrors > 0; /* Packets with bad CRC's */ 

Int EnetSyncErrors >• 0; /* Receiver out of sync */ 

int EnetTimeouts "0: /* Transmitter timeouts */ 

int EnetValidPackets - 0: 

chap kPacketAreaCWORDS.PER.PACKET«BYTES.PER_WORO+20] : 

/* Save area for kernel packets */ 

kPacket *kPacketSav« > (kPackqt *) kPacketArea: 

/* Pointer to kernel packet area */ 



/* Macro expansion to intarrupt-invoked C call to Ethernetinterrupt */ 
Ca11Hand1er(EnetInterrupt) 
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A. 6. Parentheses 

For fijiiction calls, tlic parentlicscs "belong to" the call, so there is no space between function name and 
open parentheses, ('riicrc may be some inside the parentheses to make the argument list look nice.) When 
parentheses enclose the expression for a statement (1f, fop, etc,), the parentheses may be treated as 
belonging to tlic statement (since tliey are syntactically required by the statement) so dicre is no space 
between the keyword and the expression. 

1f( (bytes « req->bytecount) <■ I0_MSG_8UFFER ) 
buffer - (char •) req->shortbuffer; 

else 

return( req->bufferPo1nter ); 

Alternatively, parentheses may be treated as belonging to the expression, so there is a space between the 
keyword and the parentliesizcd expression. 

1f (FuncAO) 

{ 

Func8( (a ■ b) 0 ); 
return (Nil); 

} 

else 

{ 

FuncC( a, b, c ); 
return (ToSender); 

} 

Note tliat spaces are used to separate operators from operands for clarity and may be selectively omitted to 
suggest precedence in evaluation. 

A. 7. Messages 

Although V is a message-based system, most services arc available by calling standard routines, so 
programming at the "message level" is rarely necessary or desirable. However, the programming of new 
servers and tlie non-standard use of services or tlie use of meSvSagcs within a program require message-level 
programming. The following conventions have been followed in V. 

Space to send or receive a message is declared of type Mcssnjic, as defined in <Venviron.h>. Standard 
message formats, as dcllned in tlie V header files, declare each message format to be a new data type. Access 
to the space for die message is made by casting a pointer to the space to be of the type of the message format 
required. This guarantees tliat enough space is reserved even when a message format is not as large as tlie 
fixcd-si/c message used by the kernel. The Ibllowing illustrates diis style. 

Read( fad. buffer, bytes ) 
File •fad: 
char 'buffer; 
int bytes: 
/• 

* Read the specified number of bytes into the buffer from the 

* file instance specified by fad^ The number of bytes read is 

* returned. 
•/ 

{ 

Message msg; 

register loRequest *request ■ (loRequest *) msg; 
register loReply •reply ■ (loReply •) msg; 
register unsigned r, count; 
register char 'buf; 
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C PROGRAMMING STYLE 



for(::) 
{ 

pequ8st->requestcode ■ REAO_IMSTANCE; 
pequest->f ileld ■ fad->fneid; 
pequest->buf f arPointep ■ buffer; 
requ9St->bytecount - bytes; 
p9quest->b1octtnumber « fad->b1ock; 

1f( Send( request, f ad->f lleserver ) 0 ) 
{ 

fad->1astexcept1on - NONEXISTENT.PROCESS: 
r8turn( 0 ); 

} 

if{ (r ■ rep1y->>rep1ycode) !■ RETRY ) break; 

. } 

fad->lastexcspt1on « r; 
count ■ rep1y'->bytecouiit; 

1f( count <■ 10 MSG.BUFFER ) 
{ 

buf ■ (char •) request*>shortbuf fer; 

for( r « 0; r < count; ++r ) *buffer++ ■ *buf++; 

} • 
return( count ); 
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— Appendix B — 
Installation Notes 



lliis document is intended to be an informal collection of information about the problems involved with 
installing and maintaining the V-System software. The reader should be familiar with the V-System as 
documented in Uic V-System manuals, and with the Unix system used for development. 



B.1. V-System Distribution 

I'hc software should be distributed on a 1600 bpi tar format tape. Licensing information and tapes can be 
obtained from: 

Office of Technology Licensing 
105 Hncina Hall 
Stanford University 
Stanford, CA 94305 
(415)497-0651 

Please report any bugs you find, or improvements you make. All the software is under copyright protection, 
so you must get a license for any further distributions. Send comments on tlie software and d(K:umcntation to 
the Arpanet address vbugsdSU-Pescadero.ARPA. New versions of the software may be rclciised from 
time to time. 

'Hie first file on the tape is the entire source directory tree for die V-System. Since the first implementation 
of the V-System is for tlie Motorola MC68000, our versions of die 68000 C compiler, assembler, and linker are 
included iis the second file on the tape. 

Note: This distribution has been booted only on Cadlinc and SUN MicroSystcms Wt)rk stations with 
MC68000S, not MC68010s, connected to a vax by a 3Mb experimental I^Uiernet, using pup boot protocols, 
'i'he next release will support Uw MC68010, 10 Mb standard KUiernet, and booting via tlie SMI network disk 
protocol. 

'I'he first step is to run tar x to extract the two files into directories in your file system wherever you have 
room. Remember to use the non-rewinding driver (e.g. /dev/rmtlZ) or die mt f sf command if you want 
to read the second file. Throughout tliis document the V-Systcm paUinames will be referred to as 
V/somcthing, and tlie 68000 directory as sun/something. 



B.2. 68000 Tools 

We normally put die 68000 tools into Aisr/sun. There are a few other required directories that are 
hardwired into a few of die makefiles, /usr/sun/include is for die include (.h) files, and /usr/sun/Iib is for 
libraries. 'ITic two major libraries diat are needed by some of the V-Systcm serve»"s are 1 1 bsf onts . a for the 
character fonts, and 11bgraph1cs.a for die SUN graphics primitives. We put binary versions of die 
stand-alone bootfiles under /usr/sun/bootfile, and put die V-System commands under /usr/sun/Vboot. 

Many of the V-Systcm makefiles invoke die "cc68" command to compile and link. Be sure you have die 
latest version of the cc68 command, with the -V option. Connect to sun/src/cmd and do a make 
install. You might want to edit die command file to put the commands in a place other dian 
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/usr/local/bin. Next connect to sun/src/graphics/Iib and do a make 1 ns tal 1 to make the graphics libraiy. 
There will be a few warnings issued by the compiler which should be ignored. 'Ilicre arc manual entries for 
the 68000 software in /usr/sun/man68. • 

Our current V-Server software requires tlic CMU packet-filtering Ethernet driver for 4,1 or 4.2 Unix. Make 
sure the maximum packet size (MTU) is large enough to fit all tlie data bytes in a kernel packet plus the 
header. This driver and the iissociatcd higher-level software is available to people who have purchased Xerox 
1100 workstations in a separate distribution. 

Users who want to do 68000 development on a 68000-based Unix machine should be able to do so with a 
small amount of work; Please report your experiences back to us so that any software or infonnation can be 
included in future releases. 

The Ipwatch family of programs under sun/diag/ip watch are very useftil to debug network problems. 
The enwatch program is used for 3Mb experimental Ethernet, and ecwateh for the 3Com interface. 
Otiiers could be added easily. It keeps a record of tlie network packets of interest which can be written to a 
log flic. Fleii.se include such a log file in all error reports. 



B,3. Makingthe V-System 

Hdit the shell script under V/net ins tall to do the appropriate insuillation procedure for your system. 
We have it ftp llic files to several other machines to automate the installation. This and a few other shell 
scripts are assumed to be in the search patli by the V-Systcm Makefiles. 'ITicsc sources arc in V/tools and 
should be installed into some directory in the search padi before making tlie rest of tlie system. Each 
directory cunaiins a file called bu1ldfil9 which us processed by the buildmaka program to produce a 
makef lie. The bull df He step includes conditional macm expansion. 

Change directory to V/11bc and do a make instalT-lncludes. This should copy the V-Systcm 
specific include files into /usr/sun/include. Then do a make and then make instal 1 under this directory. 
11iis should result in 1 1 bV. a and teamroot . b being copied into Aisr/sun/lib. 

Next change dircctoi7 to V/sePvers, and do a make followed by a make install. The Vserver is 
usually installed in /etc/Vserver and Uien a line is added to /etc/rc to start it up on system reboot. 
Give it a large argument on tlic command line, so that it can put useftil information into tlie area printed by 
the Unix ps command. It should be run. as super-user, to allow it to check access protections correctly and 
setuid to die correct user. 

'ITie following are the options available on Uie Vserver: 



°d Debug flag for die major server code. 

«g Used if your system docs not have the simultaneous group feature (4.1a systems and 

beyond have this). 

°k Kernel debug. Used to debug the kernel simulator. 

-n Network debug. Used to produce a trace of network packets scut and received. 

-p Public mode, I fill Is Hag is set then broadcast GetPid requests are answered. The default is 

to answer only requests directed specificly at tills particular hosL There must be at least 
one Vserver innning tlic -p option on any given local network. 



Then change to the V/kernel directory and do a make followed by a make Instal 1 to compile the 
kernel and put the binary into /usr/sun/bootf He. You may have to edit the makefile to configure die 
kernel Tor your I/O devices. The default is to support tlie Sun MicroSystcms Rxperimental 3M bit Hdicrnet 
interface. The 3Com Multibus l*'dicrnet Interface can also be supported. Other devices such as disk 
controllers will be supported in die next release. 
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Change directory to V/cmds and again do a make followed by a make install to compile all the 
commands. This takes a while, and uses the include files, libraries, and servers. 

Finally, change to the V/standalone directory. This directory is for bootstrapping and loading utilities. 
Currently the kernel and system team are loaded with the PUP EFTP protocol. The VI cad program is 
compiled with several different flags. By default it will ask for a first team file, and possible the name of a 
kernel. By defining the symbol firstjiteam a specific first team file can be used. 

It is also possible to use the V protocol itself to do the bootstrapping. In fact, some day we might put such a 
bootstrap into the PRO Ms to make the booting process easier. 



V-SYS:rKM 5.0 RHI'URP.NCE MANUAI, 



Al'PI'NDICES 



236 INDEX 



V-SYSTHM 5.0 RUFl'Rl'NCE MANUAL 



INDEX 



Index 





Bad Process Priority 140 


68000 7 


uaa otatc 




Bare kernel mode 75, 104 


BACKSPACE 199 


Beginning of Butter 200 


DEL 200 


Beginning of Line 11, 199 


DOWN ARROW 200 


BcU 194 


HOME key 200 


Biopsy 21 


LEFT ARROW 199 


Bits 21. 51 


UNH'-EED 199 


Black 7 


RETURN 199 


Blank lines 227 


RICI1T ARROW 199 


BIksInFtle 88 


UP ARROW 200 


BlockPosition 88 


.Open 85 


Blocks 143 




BlockSize 88 


[bin] 7, 10 


Bit 95 


[home] 10 


Boise 21 


[public] 7, 10 


I3ooting 7 




Bottom 36 


Abort 104 


Break Process 11,199 


Abort Command 11,199 


Buffer Empty 87 


Aborted 139 


Busy 140 


Abs 93 




Active 239 


CadiiQC 8 


Add Context Name 157 


Calljntnandler 220 


AddCali 118 


Cailoc 95 


AddContcxtNajnc 105 


CD 8, 21 


Adding devices 223 


Center Window 16 


Adding kernel operations 223 


Circe 95 


Addllcm 118 


Change Coniaxt 8, 37 


AddKogicaiNanic 105 


Change Current Context .91 


Adaready 2zl, 224 


Change Directory 8, 21 


A i iniit. oiiici t iNamc 


ChangcDirectory 91 


Alien 2ZZ 


Changcltem 119 


All nn 

All l/U 


v.nuiucier oci lyj 


Ama/.c 21 


i^nccKcxccs z/ 


AN1<SI ia< 
AfNol IVj 


Clear yo, i>* 


Anv lid 




Any Context J54 


acarToHOL 195 


Append Only 84,143 


Clear To HOS 194 


Arrows 35 


Qcarlior 87 


AsynchroiKHiK roniniunicatton 21 1 


Oick 15 


AiKoiTooiiiig (i4 


aieni 115 


Awaiting-rcply 209 • 


Clock 219 


AwailingKtipiy 97 


Cose 85 




• Color 116 ' 


Backspace 36. 40, 194 


Compile command 75 


Backup 37 


Concat 134 


Bad Address 139 


Config Files 79 


BadArgs 139 


Config.h 223 


Bad Block No 140 


Configuration 79 


B»d BulTcr 140 


Console 163 


Bad Byte Count 140 


Context 9,22,153 



V-SYSri'M 5.0 RI-Fl-RUNCli MANUAL 



238 



INDfiX 



Context Directories 158 
Context Request 155 
Contexts 3 
Control 11,199 
Convert^num 134 
Cooking 18.122.196 
Copy 39,95 
Copy.str 134 
Copydir 22 
Cp 22 

CR Input 122 
Create 75,104 
Create Instance L45, 195 
Create View 15 
Cneatelnstanco 85 
CrcatePipcInstance 88 
CrcatcProcess 97 
CrealeSDF 117 
CrfsiteSclection Instance 114 
CroiteScssion 105 
Creatercam 08 
CreatcVGT 120 
Creator 97 
CSname 153 
CSNII server 153 
CIRLA 200 
O'RL-a 1 1, 199 
CFRL-b 11. 199 
Cl'RL-d 11, 199 
CrRL-c U. 199 
CniL-f 11, 199 
CIRL-g 11.199 
CFRL-h 11. 199 
CFRL-ic 11.200 
CrRL-1 200 
Cl'RL-n 200 
CrRI,-p 200 
CrRI,-q 200 
CPRh-t 11,200 
ClRL-u 11.200 
CIRL-w 11,200 
CI RL-y 200 
Cl-RL-z IZ200 
Current Context Invalid 140 
Cursor 122 

Cursor Backward 11. 194, 199 

Cursor l>)wn 200 

CuRor I'orward II. 194, 199 

Cursor Motion 36 

Cunmr PuKilioii 194 

CureorUp 194.200 

Cursor Word »;ickward 12, 200 

CuRor Word I'orward 12,200 

Dale 22 
Date 22 
Debug 17 
Debugger 29. 165 
DcfaullView 120 
Define 9.22 



Define Font 121 

DcfincSynibol 118 

DEL 194 

Delay 98.103.221 

Delete 36.39 

Delete Char 195 

Delete Character 11. 199 

Delete Character Backward 11. 199 

Delete Character P'orward IJ, 199 

Delete Context Name 157 

Delete last Character 11.199 

Delete Line 11,195 

Delete to Beginning of Line 11 

Delete to End or Line IL 

Delete to Start of Line 11 

Delete View 16 

Delete Window 41 

Delete Word 36,37 

Delete Word Biick ward 11 

Delete Word I 'orward 12 

l')clctcContextiNanic . 105 

l>;lcteltem 118 

l>!lcteSDl'' 117 

l>:lctcSymboi 119 

DcleteVGT 120 

l>;lcxec 27 

Destroy 22.104 

DestroyProcess 98 

Device lirror 140 

Device server 16L 210. 218 

Device type 161 

DeviceCreaiioiiTable 223 

l>sviccs 210 

DircctToCurrcnlContcxt 106 
IXscardOutput 122 
Display Item 120 
Distributed operation 211. 222 
1>> 27 

Duplicate Name 140 

(•cho 22.122 
I:dilor 35 
t-ditSymbol 119 
l-ndofBuiTer 200 
l-ndofTile 12, 140.200 
End of Line 11,199 
IlndSymbol 118 
VxiC 87 
R|uai 134 
[•rrorSlring 135.141 
ESC-. 200 
ISC-. 200 

IZSC-HACKSHACB 200 

USC-Di'L 200 
GSC-b 12,200 
1-SC-d 12.200 
ISC-f 12.200 
rSC-h 12.200 
ISC-l 200 
Escape 11.199 



V-SYSTHM 5.0 RI'I'liRI'.NCl' MANUAL 



INDEX 



Escape Sequences 194 


GetTimc 99 


Ethernet 16.1 


GetlTY 123 


Ethernet perrormance 218 


GiveToMalloc 96 


Event 115 


Go To 39 


Event Request 196 


Grab 39 


Example 124 


Graphics 115 


Exception Request 165 


Graphics Commands 16 


ILxception S<jrvcr 165, 215 




ExccptionMessage 215 


Help 22 


Exceptions 165, 215 


Hex.value 134 


Exchange 39 


History 12 


Exec 7,197 


Hit I>:tcction 120 


Exec Control 7,16 


Horizontal line 116 


fixecProg 107 


Horizontal Reference Line 117 


Executive 7,15.75,104 




Exit 104 


I/O 83 


Ex|Minsion Depth 17 


I/O Protocol 115. 143. 193, 210 




Idcmpotenl 102 


FAppcnd 83,145 


Idle process 220 


I'Crcate 83, 144 


Ignored 194 


FDircctory 145 


Illegal Request 140 


Flixcculc 145 


Index 194 


[•Iclds 127 


Initl'XCCpiionScrvcr 165 


nic Access 37 


Initial priority 75 


Rlc Modes 83. 144 


Initial process 75 


Mlc Types 84. 143 


Initial stack 75,223 


FilcException 88 


Initialivation 210 


Htcid 90 


InquircCall 118 


rilcScryer 90 


Inquireltcm 118 


iMlclypc 90 


Insert 37 


Filled Rectangle 116 


Insert Char 195 


iMndSclccicdObjcct 120 


Insert Line 195 


Fixed Ixngih 84, 144 


Insert 1 jncfccd 37 


Mxcd Menu 38 " 


Insert With EighUi Bit Set 200 


riusli 86 


Installation 233 


I-TVJodify 83,145 


Interactive 84, 90, 144 


Font 121 


Internal Error 140 


I'orgcl 37 


Internet Server 22 


f'brward 98 


Interprocess communication 210 


(•brwarder 98 


Intornipt disable lime 218 


I'Rcad 83,144 


Inlcrmpt masking 219 


I'Vce 95 


Interrupts 220 


rschcck 59 


Invalid Context 140 


I''Scssioii 145 


Invalid I He Id 140 




Invalid Mode 140 


General Line L16 


Inverse Video 195 


Get Context Id 155 


lOnrcak 140 


Get Context Nanic 156 


10 Protocol 72 


Get I He 41 


Iptclnet 22 


Get I'lle Name 156 


Iptn 22 


GctConlextId 106 


Iris 116 


GctContaxtName 106 


Hem 115.116 


Gctl'Went 124 


Item lypc 116 


Gcti'llcNamc 106 




GctGraphicsEvcnt 123 


Kernel arguments 223 


GctGraphicsSlatus 123 


Kernel configuration 223 


GciMorcMallocSpacc 96 


Kernel Operations 213 


Gctl'id 99.222 


Kernel stack 219 


GctTcJiniRoot 99 


KernelTimeout 140 


Get TcainSize 99 


Kernel timings 217 



V-SYSTUM 5.0 RI'M-RENCE MANUAL 



240 



INDI2X 



Kernel traps 220 


Mouse 15.18.38.162 


Kcrnelops 223 


Mouse emulation 18 


Kill 37 


Mouse F.vent Request 196 


Kill Break 11.199 


Mouse Status Request 196 


KillBuJTer 38 


Move Edges 16 


Kiillnput BulTcr 200 


Move Edges + Object 16 


Kilt Program 1% 


Move Viewport 16 


Kill Region 40 


MovcFrom 99 


Kill to Und of Line 200 


MovcTo 100 


Kill Word Backward 200 


MulU Block 84,144 


Kill Word Forward 200 




Killprt}g 27 


Name Request 154 




Names 227 


I vd68 29 


Naming 210 


Uil Button 18.38 


Naming Protocol 153 


Lcll+Middlc Buuons 18 


New Line 194 


1^:11+ Right Buttons 18 


Ncwteim 23 


LF Output 122 


Next Line 194 


IJbV.a 75 


NModifyRlc 150 


Line 36, 116 


No 40 


LinclUilTer 122 


No Memory 141 


1 .inc l-diting 1 1 


NoPI)s 141 


Liiic-l-.dtling 15. 122 


No Permission 141 


Linefeed 37 - 


No Process Dcscriptont 141 


Linking 75 


No Server Resources 141 


List Type 12) 


NoCursor 122 


IJstdir 23 


Nonexistent Process 141 


Loader 76 


Nonexistent Session 141 


Ixmding Nonstandard Kernels 67 


Not Awaiting Reply 141 


LoadNcwTcam 108 


Not I'ound 141 


LoadProg 107 


Not Readable 141 


LoadTcam 108 


NoiWritcable 141 


l.ocai Name Server 8 


NQucrynic 150 


lx)gin 9.23 


NRead l>scriptor 159 


lx}gin Context 154 


NUL 194 


Logout 10,23 


Null^str 135 


I x)ngjmp 13S 


Number of devices 223 


l.owcr 135 


Number of processes 223 




Number of teiims 223 


Make Bottom 16 


Numeric 93 


Make Top 16 


NWrilc Descriptor 159 


Malloc 75,95 




Mark 40 


Object l>scriptors 158 


Math 93 


OK 139 


Memory management 209 


Open 84 


Menu 121.127 


OpenFile 85.122 


Menu. View Manager 15 


Openip 89 


Merge Windows 41 


OpenlMd 122.195 


Message I'ormat Conventions 139 


Opcnihip 89 


Message primitives 221 


OpcnStr 90 


Messages 2J0 


OpcnTcp 88 


Middle Button 18,38 


Outlino 117 


Middle-)- Right Buttons 18 




Mode 145 


Pad 15 


Mode Not Supported 141 


Pad Escape Sequences 194 


Modes 83,144 


PadFindPoint 124 


Modify Ftle 150.196 


Page l>)wn 36 


ModifyPad 123 


PageUp 36 


Mona.steries 75 


I'nged output mode 17 


Motorola 68000 215 


Pagcmodc 23 



V-SYSTEM 5.0 RI-T-HRENCE MANUAL 



INDEX 



PagcOutput 122 


Redisplay 39 


PagcOutpuiEnabIc 122 


Redraw 17. 36 


ParscLine 109 . 


RedrawPad 124 


Pcr-Process Area 77,209 


Reference Line 117 


Point 116 


Region 40 


Pointer 116 


Register Handler 165 


Popup 121 


RcgislcrScrver 113 


Power Failure 141 


Release Input BulTer 199 


Previous Word 12,200 


Release Instance 147, 196 


PrintHrror 136 


Rcleaselnstance 86 


Printf 83 


Retocaiion 75 


PrintFile 91 


Remote program execution 10 


Priority 219.221 


Rcmotei£xccute 108 


Process 97,209 


Rcmovcl'llc 90 


Process creation 221 


Removercady 221.224 


Process descriptor 219 


Repeat Search 39 


Process destruction 221 


Replacement String 40 


Process identiflcr 209 


Reply 10 L 


Process maiiagcincnt 209 


Reply code 139 . 


Process switcliing 220 


RcplyWilhScgmcnt .101 


l*roccssc8 219 


Report Gick 122 


I*roccssor altocation 209, 221 


Report Tiansition 1.22 


PROM 72 


Request code 139 


PROM monitor 104 


Request Message r'orinais 145 


Protocol 139 


Request Not Supported 141 


Public 183 


RercadMsg 101 


Public Context 154 


Resell 1 1 123 


l*ull Apart 41 


Resynch 86 


PU1* 24 


Ilk ^a^. t A t 

Retry 141 


Pwd 9, 22 . 


Return 37, 194 




Revenic Index 195 


Qsort 135 


Reverse Search 39.40 


Query File 150, 196 


Right Button 18, 38 


Query Instance 146, 195 


Root process 223 


Query Replace 39. 40 


RunProgram 108 


Querycxcc 27 




Query Kemci 100 


SamcTeam 101 


QucryPad 123 


Sanity 42 


QucryPadSi/c 123 


Save 37 


QucryPrpcessSlaic 100, 215 


Scheduling 219 


Query WorksUUionCon fig 79 


Scroll 36, 39 


Quit 36 


Scroll Region 195 


Quote 37 


SOI' 1.15 


Quote Gtaractcr 200 


Search 38. 39. 40 




Searching 38 


Rand 93 


Seek 86 


Raster 117, 118 


SeekHIock 88 


Raw 122 


Segment .102 


Redisplay Input 200 


Segments 210 


Read 87 


Select 4 1 


Read l>!Scriplor 159" 


Selected Vertical Rcfurence 1 jnc 


Kcau Instance 147, ivo 


SclcctPad L2j 


Kcaanoic o*i, t^j 


ocnu iui, 


RcadProccssSlatc 100.215 


Send-Rcceive-Rcply 217 


Ready 104.209 


Serial 23 


Real-time 209 


Serial line 162 


Rcalloc 95 


Server Not Responding 141 


RcccivcSpocinc 101 


Services 139 


RccciveWilhScgment 100 


Session 23.73 


Rectangle 116 


Sessions 9 



V-SYSTI'M 5.0 RI-l'l-.RP.NCl? MANUAL 



242 



INDliX 



Set Break Process 149, 196 


Timeout 141 


Set Instance Owner 149 


Toggle Grid 17 


Set Mark 40 


Top 36 


Set Prompt 149 


Tops-20 7 


SctlJrcakProccss 90,197 


Transparent operation 211 


ScUnstanccOwner 91 


Transpose 11 


Sctjmp 135 


Transpose Characters 200 


ScU'id 102 


Transpose Words 200 


SctTcamPriority 102 


Trap.c 223 


Sct'l'camSi/c 103 


Type 24.84.U6 


Sctllmc 103 


TypeOata 116 


SctUpArgumcnts 109 


Types 143 


SciVgUJanner 197 




Shcil 7 


Un-Kill 200 


Shiain 194 


Undcnne 9 


ShtaOut 194 


Undo 40 


Shift_lcft 135 


Unix 7. 10, 25. 71, 73. 183 


Show 24 


UnregisterServer 113 


Sibling 116 


Upper 135 


Size US 




Sleep 133 


V server 9. 10. 183 


SMi 7.S 


Validl>id 103 


Space IW 39 


ValidProgram 109 


Special Slates 36 


Variable Block 84.144 


SpcdalClose 85 


Vax 25 


Spline 117.118 


Ved 24.35 


Srand 93 


Vcnviron.h 75.139 


Slack 209 


Vertical Line 116 


Slack overflow 75 


Vertical Reference IJne 117 


Start of Line 11, 199 


VethemcLh 161 


Stancxcc 27 


Vexceptions.h 165. 215 


Stipple 116 


VGT 115, 119. 193 


Stream 84, 143 


VGTS 7,15,18,29 


Slnictured Display Rlc '115 


Vgis.h 116, 120. 121 


STS hardware ciivironnicnt 200 


VgLsexec 7 


SYS input editing 199 


View In, IJ5. 1 19, 193 


Style 227 


View Manager 7. 15, 196 


Suicide 104 


View Manager Menu 15 


Supervisor mode 219 


Vio.h 143 


Swab % 


Vioprotocoi.h 145 


Switch 220 


Virtual Graphics Tenninal 119 


Switch Input 196 


Visit 37 


Symbol 115 


VIoad 63.76 


Synchroni/ation 219 


Vmouso.h 162 


Tab 37.39,194 


Wnkeup 103 


Team 209 


Word 36 


Team descriptor 219 


Workstation 209 


I'cam Koot Message 76 


Write 37.87 


TcamRoca 76 


Write l>»criplor 159 


Tcairw 209. 119 


Write Instance 148, 1% 


Telnet 24 


Write Region 40 


Terminal Emulator 194 


Wriicable 84, 143 


TerminateScssion 106 


WriteKernelPackct 222 


Tcstaxccpt 24 


WritcProccssState 103 


Text 36,115.116,117 


Writcsiiort Instance L96 


Ttmc 73 




Time management 210 


Xmax 116 


Time primitives 221 


Xmin U6 


Timekcrnel 24 





V-SYS1"HM 5.0 RI'Fr.RENCr, MANUAL 



INDEX 



Yale 22.117 
Yank 37 

Yank to window 41 
Yes 40 
Ymax 116 
Ymin 116 

Zero 96,116 
Zoom 16 



V-SYSTEM 5.0 RI-r-r-RIiNCn MANUAL 



